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Preface 


This publication is a reference manual and contains the macro instructions that 
are used for the virtual storage access method (VSAM). It is intended for 
programmers who use VSAM macro instructions, access method services 
commands, or JCL to process data. 


Organization 


This publication contains the following major sections: 

• Chapter 1, “Macro Instruction Return Codes and Reason Codes,” contains 
return codes for macros used to open and close data sets, manage control 
blocks, and issue data management requests. 

• Chapter 2, “VSAM Macro Formats and Examples,” describes the syntax of 
each macro and includes coded examples. 

• Appendix A, “Format of Macros,” summarizes, for ease of reference, the 
format of the macros used to communicate with VSAM. 

• Appendix S, “list, Execute, and Generate Forms ©f Macros,” explains how 
to code reentrant programs with the macros that generate, modify, test, and 
display control blocks at execution. 

• Appendix C, “Operand Notation,” defines the terms used to describe the 
operand notation used in the macros that generate, modify, test, and display 
control blocks at program execution time. 

• Appendix D, “Building Parameter Lists,” describes the standard way to 
build parameter lists. 

• “Glossary of Terms and Abbreviations” defines VSAM terms. 

• Index is a subject index to this publication. 
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Prerequisite Knowledge 


Readers of this publication are assumed to have a programming background that 
includes: 

• VSAM data management 

• Catalog administration 

• Job control language 


Required Publications 

You should be familiar with the information presented in the following 

publications: 

• MVS/Extended Architecture Catalog Administration Guide , GC26-4138, 
describes the administration of tasks for catalogs and how to use the access 
method services commands to manipulate catalogs, and the objects cataloged 
in them. 

• MVS!Extended Architecture Data Facility Product Version 2: Customization , 
GC26-4267, contains consolidated customization information for the DFP 
library. 

• MVS/Extended Architecture JCL User's Guide, GC28-1351, and 

MVSf Extended Architecture JCL Reference , GC28-1352, describes the JCL 
parameters referred to in this publication and describes dynamic allocation. 

• MVSlExtended Architecture Message Library: System Messages , Volumes 1 
and 2, GC28-1376 and GC28-1377, provides a complete listing of the 
messages issued by VSAM. 

• MVS/Extended Architecture VSAM Administration Guide, GC26-4151, 
describes how to use VSAM. 

• MVS/Extended Architecture VSAM Logic, LY26-3970, describes the internal 
logic of VSAM. 


Related Publications 


Within the text, references are made to the publications listed in the table below: 
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Short Title 

Publication Title 

Order Number 

Access Method 
Services 

Reference 

MVSjExtended Architecture 
Integrated Catalog 
Administration: Access Method 
Services Reference 

GC26-4135 


M VS 1 Extended Architecture 
VSAM Catalog 

Administration: Access Method 
Services Reference 

GC26-4136 

Catalog 

Administration 

Guide 

M VS 1 Extended Architecture 
Catalog Administration Guide 

GC26-4138 

Checkpoint/ 

Restart User's 
Guide 

M VS 1 Extended Architecture 
Checkpoint! Restart User's 

Guide 

GC26-4139 

Data Facility 

Product: 

Customization 

MVS)Extended Architecture 

Data Facility Product Version 

2: Customization 

GC26-4267 

Data 

Administration: 

Macro 

Instruction 

Reference 

MVSjExtended Architecture 

Data Administration: Macro 
Instruction Reference 

GC26-4141 

Data 

Areas—JES2 

MVS (Extended Architecture 

Data Areas—JES 2 

LYB8-1191 

Data 

Areas-JES3 

MVS!Extended Architecture 

Data Areas—JES 3 

LYB8-1195 

Data Facility 
Product: Master 
Index 

MVS!Extended Architecture 

Data Facility Product Version 

2: Master Index 

GC26-4146 

Data Facility 
Product: 

Planning Guide 

MVS!Extended Architecture 

Data Facility Product Version 

2: Planning Guide 

GC26-4147 

Debugging 

Handbook 

MVS!Extended Architecture 
System Programming Library: 
Debugging Handbook , 

Volumes 1 through 5 

LC28-1164 1 

LC28-1165 

LC28-1166 

LC28-1167 

LC28-1168 

Introduction to 
the IBM 3850 

Mass Storage 
System 

Introduction to the IBM 3850 
Mass Storage System (MSS) 

GA32-0028 

JCL User's 

Guide 

MVS!Extended Architecture 

JCL User's Guide 

GC28-1351 

JCL Reference 

MVS/Extended Architecture 

JCL Reference 

GC28-1352 


Note: 

1 All five volumes may be ordered under one order number, LBOF-1015. 
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Short Title 

Publication Title 

Order Number 

OS/VS Mass 
Storage System 
Services: 

Reference 

Information 

OSJ VS Mass Storage System 
(MSS) Services: Reference 
Information 

GC35-0017 

RACF General 
Information 

Manual 

OS) VS2 MVS Resource Access 
Control Facility (RACF): 

General Information Manual 

GC28-0722 

Supervisor 

Services and 

Macro 

Instructions 

MVS/Extended Architecture 
System Programming Library: 
Supervisor Services and Macro 
Instructions 

GC28-1154 

System Messages 

MVS/Extended Architecture 
Message Library: System 
Messages, Volumes 1 and 2 

GC28-1376 

and 

GC28-1377 

System 

Modifications 

MVS/Extended Architecture 
System Programming Library: 
System Modifications 

GC28-1152 

TSO Command 
language 

Reference 

OS/VS 2 TSO Command 
Language Reference with 
MVS/Oxtended Architecture 
supplement 

GC28-0646 

SD23-0259 

TSO Terminal 
User's Guide 

M VS/ Extended A rchitecture 

TSO Terminal User's Guide 

GC28-1274 

VSAM 

Administration 

Guide 

MVS/Extended Architecture 
VSAM Administration Guide 

GC26-4151 

VSAM Logic 

M VS/ Extended A rchitecture 
VSAM Logic 

LY26-3970 

31-Bit 

Addressing 

M VS/ Extended A rchitecture 
System Programming Library: 

31-Bit Addressing 

GC28-1158 


Notational Conventions 

A uniform system of notation describes the format of VSAM macro instructions. 
This notation is not part of the language; it merely provides a basis for describing 
the structure of the macros. 

The macro format illustrations in this book use the following conventions: 

• Brackets [ J indicate optional parameters. 

• Braces {} indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 

• Items separated by a vertical bar (|) represent alternative items. No more 
than one of the items may be selected. 


VI MVS/XA VSAM Administration: Macro Instruction Reference 




An ellipsis (...) indicates that multiple entries of the type immediately 
preceding the ellipsis are allowed. 

Other punctuation (parentheses, commas, etc.) must be entered as shown. 

BOLDFACE type indicates the exact characters to be entered. Such items 
must be entered exactly as illustrated (in uppercase, except in TSO). 

Italics type specifics fields to be supplied by the user. 

BOLDFACE'UNDERSCORED type indicates a default option. If the 
parameter is omitted, the underscored boldface value is assumed. 

A ‘ ’in the macro format indicates that a blank (an empty space) must be 
present before the next parameter. 
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Summary of Changes 


l Release 3.0, June 1987 


| New Programming Support 

• A new parameter, MODE= 24J3i, has been added to the BLDVRP, 

CLOSE, DLVRP and OPEN macros. 

• A new parameter, RMODE31 = (ALL|BUFF|CB|NONE), has been added to 
the ACB, BLDVRP, GENCB and MODCB macros. This new parameter 
replaces the MACRF = AMODE31 subparameter in the ACB, 

GENCB-ACB, and MODCB-ACB macros and the LOC parameter in the 
BLDVRP and GENCB-RPL macros. 

• A new specification, DATA|INDEX, has been added to the TYPE parameter 
in the BLDVRP macro. 

-* A new' option, LDS, lias been added to the TESTCB-ACB macro. 

• The parameter LOC = BELOWjANY has been added to the GENCB macro. 

• The BLDVRP, CLOSE, DLVRP, and OPEN parameter lists, the ACB, and 
other control blocks and I/O buffers may now reside above or below 16 
megabytes. 

• New codes have been added to the logical error reason codes in the feedback 
field of the request parameter list. 

• New codes have been added to the return codes from BLDVRP and some 
existing code descriptions have been changed. 

• Some code descriptions have been changed in the open reason codes in the 
error field of the access method control block. 


Summary of Changes IX 




| Service Changes 


| Information has been added to reflect technical service changes. 

| Version 2 Publications 

| The tables containing the macro operand expressions in Appendix C, “Operand 

| Notation” have been deleted. 

Release 2.0, June 1986 

Service Changes 

Information has been added to reflect technical service changes. 

Version 2 Publications 

The preface has. been updated to include order numbers, for Version 2. 

Release 1.0, April 1985 

A new parameter, ACTION = REFRESH, has been added to the VERIFY 
macro. 

A new parameter, IOPID, has been added to the EXLST macro. This parameter 
permits termination of existing I/O and prevention of new I/O. 
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Chapter 1. Macro Instruction Return Codes and Reason Codes 


This chapter describes the return codes and reason codes generated by the macro 
instructions used to open and close a data set, manage VSAM control blocks, 
and issue data processing requests. 

VSAM sets the return codes in register 15. These return codes are paired with 
reason codes set in the access method control block (ACB) and the request 
parameter list (RPL). Reason codes set in the ACB indicate open or close errors. 
Reason codes set in the RPL indicate record management errors. 

This manual lists return codes and reason codes in decimal and hexadecimal 
values. The decimal value is shown first, followed by the hexadecimal value in 
parentheses. Format descriptions and examples of each macro are shown in 
Chapter 2, “VSAM Macro Formats and Examples” on page 33. 


Return Codes and Reason Codes from OPEN 

When your program receives control after issuing an OPEN macro, the return 

code in register 15 indicates whether all of the VSAM data sets were opened 

successfully: 

Return 

Code Condition 

0(0) All data sets were opened successfully. 

4(4) All data sets were opened successfully, but one or more warning 

messages were issued (reason codes less than X'80'). 

8(8) At least one data set (VSAM or non-VSAM) was not opened 

successfully; the access method control block was restored to the 
contents it had before OPEN was issued; or, if the data set was 
already open, the access method control block remains open and 
usable and is not changed. 

12(C) A non-VSAM data set was not opened successfully when a 

non-VSAM and a VSAM data set were being opened at the same 
time; the non-VSAM data control block was not restored to the 
contents it had before OPEN was issued (and the data set cannot be 
opened without restoring the control block). 
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If register 15 contains a nonzero return code, you can use the SHOWCB macro 
to display the corresponding reason code. The SHOWCB macro displays the 
error field in each access method control block specified by the OPEN macro. 
(See “SHOWCB Macro (Display Fields of an Access Method Control Block)” 
on page 133.) Figure 1 lists the reason codes that may appear in this error field. 
VSAM also writes a message to the operator console and to the programmer's 
listing to explain the error further. For a listing of VSAM messages, see System 
Messages. 


Reason 

Code 

0 ( 0 ) 


76(4C) 

92(5C) 

96(60) 

100(64) 

104(68) 

108(6C) 

116(74) 


118(76) 


Figure 1 


Condition 

One of the following conditions exists: 

• VSAM is processing the access method control block for some 
other request. 

• The access method control block address is invalid. 

Warning message: The interrupt recognition flag (IRF) was detected 
for a data set opened for input processing. 

Warning message: Inconsistent use of CBUF processing. Sharing 
options differ between index and data, components. 

Warning message: An unusable data set was opened for input. 

Warning message: OPEN encountered an empty alternate index that 
is part of an upgrade set. 

Warning message: The time stamp of the volume on which a data set 
is stored docsn t match the system time stamp in the data set's catalog 
record; this indicates that extent information in the catalog record 
may not agree with the extents indicated in the volume s VTOC. 

Warning message: The time stamps of a data component and an 
index component do not match; this indicates that either the data or 
the index has been updated separately from the other. 

Warning message: The data set was not properly closed and cither 
OPEN's implicit verify was unsuccessful or the user specified that 
OPEN's implicit verify should not be executed. 

A previous VSAM program may have abnormally terminated. Data 
may be lost if processing continues; the access method services 
VERIFY command may be used to cause the data set to be properly 
closed. For a description of the VERIFY command, see Access 
Method Services Reference. In a cross-system shared DASD 
environment, a return code of 116 can have two meanings: (1) the 
data set was not properly closed, or (2) the data set is opened for 
output on another processor. 

Warning message: The data set was not properly closed but OPEN's 
implicit verify was successfully executed. 

(Part 1 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 


/ 
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Reason 

Code 

128(80) 

132(84) 


136(88) 

140(8C) 

144(90) 

145(91) 

148(94) 

152(98) 

160(A0) 


Figure 1 


Condition 

DD statement for this access method control block is missing or 
invalid. 

One of the following errors occurred: 

• Not enough storage was available for work areas. 

• llie required volume could not be mounted. 

• An uncorrectable I/O error occurred while VSAM was reading 
the job file control block (JFCB). 

• The format-1 DSCB or the catalog cluster record is invalid. 

• The user-supplied catalog name does not match the name on the 
entry. 

• r rhe user is not authorized to open the catalog as a catalog. 

Not enough virtual storage space is available in your program's 
address space for work areas, control blocks, or buffers. 

The catalog indicates this data set has an invalid physical record size. 

An uncorrectable I/O error occurred while VSAM was reading or 
writing a catalog record. 

An uncorrectable error occurred in the VSAM volume data set 
(WDS). 

No record for the data set to be opened was found in the available 
catalog(s), or an unidentified error occurred while VSAM was 
searching the catalog. For the catalog return code, see system 
message IDC3009I in System Messages. 

Authorization checking has failed for the following reasons: 

1. The password specified in the access method control block for a 
specified level of access doesn't match the password in the catalog 
for that level of access. 

2. RACF failure. For the catalog return code, see system message 
IDC3009I in System Messages. 

The operands specified in the ACB or GENCB macro are 
inconsistent either with each other or with the information in the 
catalog record. 

One of these conditions has been detected: 

• For option ACBRST 
— Path processing 

- LSR|GSR 

• For option ACBIC1 

- LSR|GSR 

- KSDS 

(Part 2 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 


Chapter 1. Macro Instruction Return Codes and Reason Codes 3 




Reason 

Code 


164(A4) 

168(A8) 

176(B0) 

180(B4) 

184(B8) 

188(BC) 

192(C0) 
Figure 1 


Condition 


— Path processing 
— Sequence set with data 
— Replicated index 
— Blocksize not equal to Cl size 

• For option ACBUBF 

- LSRJGSR 

— ACBCNV not specified 
— ACBKEY specified 
— ACBADR specified 

• For option ACBSDS 

- LSRJGSR 

— Path processing 
— Upgrade processing 

• For option ACBCBIC 

- LSRJGSR 

— ACBICI not specified 

• For miscellaneous options 

— BufTcrspace specified and the amount is too small to process 
the data set 

— Volume not mounted 
— Frying to open an empty data set for input 

An uncorrectable I/O error occurred while VSAM was reading the 
volume label. 

The data set was not available for the type of processing you 
specified, or an attempt was made to open a reusable data set with the 
reset option while another user had the data set open. The data set 
may have the INHIBIT attribute specified. 

The data set cannot be opened for CBUF processing because it was 
already opened for non-CBUF processing. Or the data set has 
conflicting CBUF attributes for the data and index components of the 
ACB. 

An error occurred while VSAM was attempting to fix a page of 
virtual storage in real storage. 

A VSAM catalog specified in JCL either does not exist or is not 
open, and no record for the data set to be opened was found in any 
other catalog. 

An uncorrectable I/O error occurred while VSAM was completing an 
I/O request. 

The data set indicated by the access method control block is not of 
the type that may be specified by an access method control block. 

An unusable data set was opened for output. 

(Part 3 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 

Code 

193(C1) 

196(C4) 

200(C8) 

204(CC) 

205(CD) 

208(D0) 

212(D4) 

216(D8) 

220(DC) 

224(E0) 

228(E4) 

^32(E8) 

236(EC) 

240(F0) 

244(F4) 

Figure 1 


Condition 

The interrupt recognition flag (IRF) was detected for a data set 
opened for output processing. 

Access to data was requested via an empty path. 

The Format-4 DSCB indicates that the volume is unusable. There 
was an error in CONVERTV to convert the volume from cither real 
to virtual or virtual to real. 

The ACB MACRF specification is GSR and caller is not operating in 
supervisor protect key 0 to 7, or ACB MACRF specification is CBIC 
(Control Blocks in Common) and caller is not operating in supervisor 
state with protect key 0 to 7. 

ITie ACBCATX option or VSAM volume data set OPEN was 
specified and the calling program was not authorized. 

The ACB MACRF specification is GSR and caller is using an 
OS/VS 1 system. 

ITie ACB MACRF specification is GSR or LSR and the data set 
requires load mode processing. 

The ACB MACRF specification is GSR or LSR and the key length 
of the data set exceeds the maximum key length specified in 
BLDVRP. 

llie ACB MACRF specification is GSR or LSR and the data set's 
control interval size exceeds the size of the largest buffer specified in 
BLDVRP. 

Improved control interval processing is specified and the data set 
requires load mode processing. 

The ACB MACRF specification is GSR or LSR and the VSAM 
shared resource table (VSRT) does not exist (no buffer pool is 
available). 

Reset was specified for a nonreusable data set and the data set is not 
empty. 

A permanent staging error occurred in MSS (ACQUIRE). 

Format-4 DSCB and volume timestamp verification failed during 
volume mount processing for output processing. 

llie volume containing the catalog recovery area was not mounted 
and not verified for output processing. 

(Part 4 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Return Codes from CLOSE 


When your program receives control after it has issued a CLOSE macro, a return 
code in register 15 indicates whether all the VS AM data sets were closed 
successfully: 

Return 

Code Condition 

0(0) All data sets were closed successfully. 

4(4) At least one data set (VSAM or non-VSAM) was not closed 
successfully. 

If register 15 contains 4, you can use SIIOWCB to display the ERROR field in 
each access method control block to find out whether a VSAM data set wasn't 
closed successfully and why not. (See “SHOVVCB Macro (Display Fields of an 
Access Method Control Block)” on page 133.) Figure 2 gives the reason codes 
that the ERROR field may contain following CLOSE. In addition to these 
reason codes, VSAM writes a message to the operator's console and the 
programmer's listing to further explain the error. For a listing of these messages, 
see System Messages. 


Return 

Code Condition 

0(0) No error (set when register 15 contains 0). 

4(4) The data set indicated by the access method control block is already 
closed. 

129(81) TCLOSE was issued against a media manager's structure. 

132(84) An uncorrectable I/O error occurred while VSAM was reading the 
job file control block (JFCB). 

136(88) Not enough virtual storage was available in your program's address 
space for a work area for CLOSE. 

144(90) An uncorrectable I/O error occurred while VSAM was reading or 
writing a catalog record. 

145(91) An uncorrectable error occurred in the VSAM volume data set 
(WDS). 

148(94) An unidentified error occurred while VSAM was searching the 
catalog. 

Figure 2 (Part 1 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Return 

Code Condition 

184(B8) An uncorrectable I/O error occurred while VS AM was completing 
outstanding I/O requests. 

236(EC) A permanent destaging error occurred in MSS (RELINQUISH). 
With temporary CLOSE, a destaging error or a staging error 
(ACQUIRE) occurred. 

Figure 2 (Part 2 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 


OPEN/CLOSE Message Area for Multiple Reason or Warning 
Messages 


During the execution of an OPEN, CLOSE, or TYPE = T option of CLOSE, 
more than one error condition may be detected. However, the ACB error flag 
field can only accommodate one warning or error condition. In order to receive 
multiple error or warning conditions, you may specify an optional message area. 
VSAM will accumulate error messages from an OPEN, CLOSE, or TYPE = T 
option in this message area. 

Multiple messages will be supplied when you specify nonzero values in the 
MAREA and MLEN parameters of the ACB. If MAREA or MLEN is not 
specified or is zero, no error or warning information is stored into the message 
area. The ACB error flag field is then the only indication for errors or warnings. 
If MAREA and MLEN are specified and if the message area is too small to 
accommodate all messages, the last incoming messages are dropped. However, 
you will be given an indication of the number of warnings and me sages that 
occurred. 

The message area provided by VSAM is subdivided into two parts: 

• The message area header 

• The message list 


Message Area Header 


The message area header contains statistical, pointer, and general information. Its 
contents are unrelated to the individual messages. The format of the message 
area header is shown in Figure 3 on page 8. 
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Byte 0 

Flag Byte 


bit 0=1 

Full message area header has 
been stored. 


bit 0=0 

Only flag byte of message area 
header has been stored. 

(Implies that no messages 
have been stored.) 


bits 1-7 

Reserved (set to binary zeros) 

Bytes 1-2 

Length of message area header (includes flag byte 
and length byte) 

Byte 3 

Request type code: 


X'01' 

OPEN 


X'02' 

CLOSE 


X'03' 

TCLOSE 

Bytes dU 

ddname used for ACB 

Bytes 12-13 

Total number of messages (error or warning 
conditions) issued by OPEN/CLOSE/TCLOSE 

Bytes 14-15 

Number of messages stored by OPEN/CLOSE/TCLOSE 
into message area 

Bytes 16-19 

Address of message list, for example, of first 
message in message area 


Figure 3. Format of the Message Area I leader 


The function of the ACB error flag field remains unchanged whether or not this 
optional message area is specified. At the end of an OPEN, CLOSE, or 
TCLOSE, this field contains either X f 00 ’ (indicating no error or warning 
condition occurred) or a nonzero code. The ACB error flag byte stores the 
nonzero OPEN/CLOSE/TCLOSE reason code corresponding to the error or 
warning condition that occurred with the highest severity. 

Message area header information is only stored when a warning or error 
condition is detected; that is, when the ACB error flag field is set to a nonzero 
value. The header information consists of the flag byte only if the message area 
length (MLEN) is not large enough to accommodate the full message area 
header. In this case, bit 0 of the flag byte will be zero. Before accessing the 
message header information (bytes 1 through 19), test byte 0 to see if more 
information is stored. If MLEN = 0, no header information is stored, not even 
the flag byte. If the full message area header is stored, bytes 1 and 2 contain its 
actual length. Your program should be sensitive to this length when interrogating 
the message area header. 
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The message list contains individual messages corresponding to detected warning 
or error conditions. Bytes 16 through 19 of the message area header point to the 
location of the message list within the message area. If the message area header is 
not stored completely (bit 0 of byte 0 is 0), the location of the message list is not 
provided. Within the message list, individual messages are stored as a contiguous 
string of variable-length records. Bytes 14 and 15 of the message area header 
contain the number of messages stored. Check for a nonzero stored message 
count before investigating the message list. However, messages may not be 
stored even if the ACB error flag byte contains a nonzero value and the message 
area header bit 0 of byte 0 is 1. For example, no messages will be stored if 
MLEN is not large enough to allow at least one message to be stored. 

The format of the individual messages is given in Figure 4. 


Bytes 0-1 Length of message including these two bytes. 

Byte 2 ACB error flag code corresponding to the error or warning 

condition represented by this message. 

Byte 3 Function type code: 

Specifies which dsnamc, if any, is stored in bytes 4 through 47 of 

the message. 

X'00' no dsnamc stored. Bytes 4-47 of the message contain 
binary zeros. The error warning condition is not clearly 
related to a component, or VSAM was unable to identify 
or obtain the cluster name of the component in error. 

This code is used only if the ddname of the ACB does not 
identify a valid DD statement, or VSAM was unable to 
obtain the dsnamc contained in the DD statement. 

X'OT dsname contained in DD statement is stored. The error 
or warning condition is not clearly related to a 
component, or VSAM was unable to identify or obtain 
the cluster name of the component in error. 

X'02' dsname (cluster name) of base cluster stored. Error 
occurred during OPEN/CLOSE/TCLOSE for base 
cluster. 

X'03' dsname (cluster name) of alternate index component 

stored. Error occurred during OPEN/CLOSE/TCLOSE 
for alternate index component. 

X'04' dsnamc (cluster name) of member of upgrade set stored. 
Error occurred during OPEN/CLOSE/TCLOSE for this 
member of the upgrade set. 


Bytes 4-47 Binary zeros (function type code = X'00') or a dsname as described 
by byte 3. 


Figure 4. Format of Individual Messages in Message List 
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Bytes 0 and 1 of each message specify its actual length. Because messages vary in 
length, you will need to know the actual length of each message in order to do 
your processing. 

Byte 2 of the message contains the ACB error flag code; it does not indicate that 
a dsname has been stored. Depending on the condition that raised the ACB 
error flag code, either no dsname or different types of dsnames (DD, base cluster, 
alternate index, or upgrade set member) may be stored. (The same condition 
may be detected both when opening the base cluster and when opening a 
member of the upgrade set. For example, an I/O error may occur when trying to 
obtain the dsname for the component in error.) Bytes 4 through 47 of the 
message can contain a dsname, but do not specify its type. Only byte 3 of the 
message specifies whether a dsname has been stored and, if so, its type. 


Control Block Manipulation Macro Return Codes and Reason Codes 

The GENCB, MODCB, SIIOWCB, and TESTCB macros are executable (unlike 
the ACB, EXLST, and RPL macros). They cause control to be given to VSAM 
to perform the indicated task. VSAM indicates if the task was completed by a 
return code in register 15: 


Return 


Code 

Condition 

0(0) 

Task completed. 

4(4) 

Task not completed. 

8(8) 

An attempt was made to use the execute form of a macro to modify a 
keyword that isn't in the parameter list. (See Appendix B, “List, 
Execute, and Generate Forms of Macros” on page 171.) 


An error can occur because you specified the operands incorrectly or, if you 
constructed a parameter list yourself, because the parameter list was coded 
incorrectly. See Appendix D, “Building Parameter Lists” on page 183, for an 
explanation of how to construct parameter lists for GENCB, MODCB, 
SIIOWCB, and TESTCB. 

When Mgrster f y^matn»4MCgrstC’r > feieasoireodo, indicating, wbjtj 

VSArftftftftftfrt'rperfonikthe task, you construct the parameter list, register 0 

can contain reason codes 1, 2, 3, 10, 14, 20, and 21. Figure 5 on page 11 
describes each reason code that can be returned in register 0. 
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Reason 

Code 

Applicable 

Macros 1 

Reason VSAM Couldn’t Perform the Task 

KD 

G,M,S,T 

The request type (generate, modify, show, or test) is 
invalid. 

2(2) 

G,M,S,T 

The block type (access method control block, exit list, or 
request parameter list) is invalid. 

3(3) 

G,M,S,T 

One of the keyword codes in the parameter list is invalid. 

4(4) 

M,S,T 

The block at the address indicated is not of the type you 
indicated (access method control block, exit list, or request 
parameter list). 

5(5) 

S,T ^ 

Access method control block fields were to be shown or 
tested, but the data set is not open or it is not a VSAM 
data set. 

6(6) 

S,T 

Access method control block information about an index 
was to be shown or tested, but no index was opened with 
the data set. 

7(7) 

M,S 

An exit list was to be modified, but the list was not large 
enough to contain the new entry; or an exit was to be 
modified or shown but the specified exit wasn't in the exit 
list. (With TESTCB, if the specified exit address isn't 
present, you get an unequal condition when you test for 
it.) 

8(8) 

G 

There isn't enough virtual storage in your program's 
address space to generate the access method control 
block(s), exit list(s), or request parameter list(s) and no 
work area outside your address space was specified. 

m 

<3, S 

The work area specified was too small for generation or 
display of the indicated control block or fields. 

10(A) 

G,M 

With GENCB, exit list control block type was specified 
and you specified an exit without without giving an 
address. With MODCB, exit list control block type was 
specified and you specified an exit without giving an 
address; in this case, either active or inactive must be 
specified, but load cannot be specified. 

11(B) 

M 

Either (1) a request parameter list was to be modified, but 
the request parameter list defines an asynchronous request 
that is active (that is, no CHECK or ENDREQ has been 
issued on the request) and thus cannot be modified; or (2) 
MODCB is already issued for the control block, but 
hasn't yet completed. 


Figure 5 (Part 1 or 2). GENCB, MODCB, SHOWCB, and TESTCB Reason Codes 
Returned in Register 0 
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Reason Applicable 
Code Macros 1 

12(C) M 

13(D) M 

14(E) G,M,T 

15(F) G,S 
16(10) G,M,S,T 

19(13) M,S f T 

20(14) S 
21(15) S,T 
22(16) S 


Figure 5 (Part 2 of 2). 

Note to Figure 5: 

1 G-GENCB, M = 


Reason VSAM Couldn’t Perform the Task 

An access method control block was to be modified, but 
the data set identified by the access method control block 
is open and thus cannot be modified. 

An exit list was to be modified, and you attempted to 
activate an exit without providing a new exit address. 
Because the exit list indicated docs not contain an address 
for that exit, your request cannot be honored. 

One of the option codes (for MACRF, ATRB, or 
OPTCD) has an invalid combination of option codes 
specified (For example, OPTCD = (ADR, SKP)). 

The work area specified did not begin on a fullword 
boundary. 

A VTAM keyword or subparameter was specified but the 
AM = VTAM parameter was not specified. AM = VTAM 
must be specified in order to process a VTAM version of 
the control block. 

A keyword was specified which refers to a field beyond 
the length of the control block located at the address 
indicated. (For example, a VTAM keyword was specified, 
but the control block pointed to was a shorter, 
non-VTAM block.) 

Keywords were specified which apply only if 
MACRF = LSR or GSR. 

The block to be displayed or tested does not exist because 
the data set is a dummy data set. 

AM = VTAM was specified and the RPL FIELDS 
parameter conflicts with the RPLNIB bit status. Either 
RPLFIELDS = NIB was specified and the RPLNIB was 
off, or RPL FIELDS = ARG was specified and the 
RPLNIB bit was on. 


GKNCB, MODCB, SIIOVVCB, and TESTCB Reason Codes 
Returned in Register 0 


MODCB, S — SIIOWCB, T=TESTCB 
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Record Management Return Codes and Reason Codes 


The following record management macros give return codes and reason codes in 
the feedback area of the RPL: GET, PUT, POINT, ERASE, CHECK, 
ENDREQ, GETIX, PUTIX, ACQRANGE, CNVTAD, MNTACQ, 

MRKBFR, SCHBFR, and WRTBFR. 

| The feedback word in the RPL consists of four bytes: 

| Byte Description 

| 1 Problem determination function (PDF) code. This code is used to locate 

| the point in VS AM record management at which a logical error 

| condition is recognized. A description of the returned PDF code is 

| located in the IDARMRCD macro. 

| 2 RPL return code. This code is returned in register 15. 

| 3 Component code. This code specifies the component being processed 

| when the error occurred. 

| 4 Reason code. This code, when paired with the return code in byte 2, 

| specifies the actual reason for cither a successful completion or an error. 

| Bytes 2 through 4 make up the RPL feedback area. An explanation of the codes 

| that appear in these three bytes follows. 

j Bytes 3 and 4 make up the RPL condition code. An explanation of this code 

| also follows. 

| The field name of each byte appears within parentheses in the following figure. 


RPL Feedback Word (4 bytes) 


RPL Feedback Area (3 bytes) 
| , 


RPL Condition Code (2 bytes) 


! 


PDF Code 
(RPLFUNCD) 

Return Code 
(RPLRTNCD) 

Component Code 
(RPLCMPON) 

Reason Code 
(RPLERRCD) 


For more information bn the RPL feedback word, see VS AM Logic. 

Return Codes (RPLRTNCD) 

The meaning of the return code depends on whether processing is asynchronous 
or synchronous. 
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Asynchronous Request 

After you issue an asynchronous request for access to a data set, VSAM issues a 
return code in register 15 to indicate whether the request was accepted, as follows: 

Return Code 

(RPLRTNCD) Condition 

0(0) Request was accepted. 

4(4) Request was not accepted because the request parameter list 

indicated by the request (RPL = address) was active for another 
request. 

If the asynchronous request was accepted, issue a CHECK after doing your other 
processing so VSAM can indicate in register 15 whether the request was 
completed successfully, set a return code in the feedback area, and exit to any 
appropriate exit routine. If the request was not accepted, you should either wait 
until the other request is complete (for example, by issuing a CHECK on the 
request parameter list) or terminate the other request (using ENDREQ). Then 
you can reissue the rejected request. 

Synchronous Request 

After a synchronous request, or a CHECK or ENDREQ macro, the return code 
in register 15 indicates whether the request was completed successfully, as follows: 

< 

Return Code 

(RPLRTNCD) Condition 

0(0) Request completed successfully. 

4(4) Request was not accepted because the request parameter list 

indicated by the request (R PL=address) was active for another 
request. 

8(8) Logical error; specific error is indicated in the feedback area in 

the RPL. 

12(C) Physical error; specific error is indicated in the feedback area in 

the RPL. 

Component Codes (RPLCMPON) 

When a logical or physical error occurs, VSAM uses the component code field of 
the RPL to identify the component being processed when the error occurred and 
indicates whether the alternate index upgrade set is correct following the request 
that failed. The component code can be displayed and tested by using the 
SHOWCB and TESTCB macros. The codes and their meanings are given in 
Figure 6 on page 15. 
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Note: The component code (byte 3 of the RPL feedback word) and the reason 
code (byte 4 of the RPL feedback word) make up the 2-byte RPL condition 
code. 

For more information on the RPL feedback word see VS AM Logic. 


Component Code 
(RPLCMPON) 

What Was Being 
Processed 

Upgrade Set Status 

0(0) 

Base cluster 

Correct 

1(1) 

Base cluster 

May be incorrect 

2(2) 

Alternate index 

Correct 

3(3) 

Alternate index 

May be incorrect 

4(4) 

Upgrade set 

Correct 

5(5) 

Upgrade set 

May be incorrect 


Figure 6. Component Codes Provided in the RPL 


| Reason Codes (RPLERRCD) 

The 0, 8, and 12 return codes in register 15 are paired with reason codes in the 
feedback area of the request parameter list. 

The reason codes in the feedback area of the request parameter list can be 
examined with the SHOWCB or TESTCB macro. You may code your 
examination routine immediately following the request macro. Logical errors, 
physical errors, and reaching the end of the data ret ah cause VS AM to exit to 
the appropriate exit routine, if you provide one. 

Coordinate error checking in your program with your error-analysis exit routines. 
If they terminate the program, for instance, you would not need to code a check 
for an error after a request. But if a routine returns to VSAM to continue 
processing, you should check register 15 after a request to determine whether 
there was an error. Even though the error was handled by an exit routine, you 
may want to modify processing because of the error. 

Reason Code (Successful Request) 

When the request is completed, register 15 is set to indicate the status of the 
request. A reason code of 0 indicates successful completion. Nonzero codes are 
set for a variety of other reasons. Figure 7 on page 16 lists these codes and their 
meanings. 
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Reason Code 

(RPLERRCD) 

When Register 

15-0(0) Condition 

0(0) Request completed successfully. 

4(4) Request completed successfully. For retrieval, VSAM mounted 

another volume to locate the record; for storage, VSAM allocated 
additional space or mounted another volume. 

8(8) For GET requests, indicates a duplicate alternate key exists 

(applies only when accessing a data set using an alternate index 
that allows nonunique keys); for PUT requests, indicates that a 
duplicate key was created in an alternate index with the 
nonunique attribute. 

12(C) All buffers, except for the buffer just obtained, may have been 

modified and may need to be written; issuance of WRTBFR 
macro is suggested. 

16(10) The sequence-set record does not have enough space to allow it 

to address all of the control intervals in the control area that 
should contain the record. The record was written into a new 
control area. 

20(14) Data set is not on virtual DASD for 

CNVTAD/ M NTACQ/ACQ RANGE request. 

24(18) Buffer found but not modified; no buffer writes performed. 

28(1C) Control interval split indicator was detected during an addressed 

GET NUP request. 

32(20) Request deferred for a resource held by the terminated RPL is 

asynchronous and cannot be restarted by TERMRPL. 

36(24) Possible data set error condition was detected by TERMRPL: 

• The request was abnormally terminated in the middle of its 
I/O operation. 

• One of the data/index BUFCs of the string contains data that 
needs to be written (BUFCMW = ON) but it was invalidated 
by TERMRPL. 

40(28) Error in PLH data BUFC pointer was detected by TERMRPL. 

Figure 7. Successful Completion Reason Codes in the Feedback Area of the Request 
Parameter List 


/ 
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Reason Code (Logical Errors) 


If a logical error occurs and you have no LERAD routine (or the LERAD exit is 
inactive), VSAM returns control to your program following the last executed 
instruction. (“User-Written-Exit Routines” in Data Facility Product: 
Customization describes the LERAD routine.) The return code in register 15 
indicates a logical error (8), and the feedback area in the request parameter list 
contains a reason code identifying the error. Register 1 points to the request 
parameter list. 

Figure 8 gives the reason codes shown in the feedback area and explains their 
meanings. 


Reason Code 
(RPLERRCD) 

When Register 
15-8(8) Condition 


4(4) 


_ y 8(8) 

12(C) 


16(10) 


End of data set encountered (during sequential or 
skip sequential retrieval), or the search argument 
is greater than the high key of the data set. 

Either no EODAD routine is provided, or one is 
provided, returned to VSAM, and the processing 
program issued another GET. (“User-Written-Exit 
Routines” in VSAM Administration Guide describes 
the EODAD routine.) 

You attempted to store a record with a duplicate 
key, or there is a duplicate record for an 
alternate index with the unique key option. 

A key sequence check was performed and an error was 
detected in one of the following processing 
conditions: 

For a key-sequenced data set 

— PUT sequential or skip-sequential processing 
— GET sequential, single string input only 
— GET skip-sequential processing and the previous 
request is not a POINT 

• For a relative record data set 

— GET skip-sequential processing 
— PUT skip-sequential processing 

Record not found, or 

the RBA is not found in the buffer pool. 


Figure 8 (Part I of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 = 8(8) Condition 

20(14) The RBA is found, but the buffer is under the exclusive control of 
another request. With this condition, it is possible to also have 
buffers invalidated. Or, the control interval is for a record already 
held in exclusive control by another requester. 

Note: If the RPL message area is correctly specified, the following 
information is returned: 

Offset Length Discussion 

0 4 Address of RPL in exclusive 

control 

4 1 Flag Byte: 

X f 00 * - neither RPL is doing a 
control area split 

X T 01 * - current RPL is attempting a 
control area sput 

X ’ 02 ’ - other RPL is doing 
a control area split 

24(18) Record resides on a volume that can't be mounted. 

28(IC) Data set cannot be extended because VS AM can't allocate 

additional direct access storage space. Either there is not enough 
space left to make the secondary allocation request or you 
attempted to increase the size of a data set while processing with 
SHAREOPTIONS = 4 and DISP=SHR. 

32(20) You specified an RBA that doesn't give the address of any data 
record in the data set. 

36(24) Key ranges were specified for the data set when it was defined, but 
no range was specified that includes the record to be inserted. 

40(28) Insufficient virtual storage in your address space to complete the 
request. 

44(2C) Work area not large enough for the data record or for the buffer 
(GET with OPTCD = MVE). 

Figure 8 (Part 2 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 = 8(8) Condition 

48(30) Invalid options, data set attributes, or processing conditions 
specified for TERMRPL request: 

• CNV processing 

• The specified RPL is asynchronous 

• Chained RPLs 

• Path processing 

• Shared resources (LSR/GSR) 

• Load mode 

• Relative record data set 

• Data set contains spanned records 

• User not in key 0 and supervisor state 

• End-of-volume in process (secondary allocation) 

52(34) The previous request was TERMRPL. 

64(40) There is insufficient storage available to dynamically add another 
string. Or, the maximum number of placeholders that may be 
allocated to the request has been allocated, and a placeholder is not 
available. 

68(44) You attempted to use a type of processing (output or control 

interval processing) that was not specified when the data set was 
opened. 

72(48) You made a keyed request for access to an entry-sequenced data 
set, or you issued a GETIX or PUTIX to an entry-sequenced or 
relative record data set. 

76{4C) You issued an addressed or control interval PUT to add to a 

key-sequenced data set, or you issued a control interval PUT to a 
relative record data set. 

80(50) You issued an ERASE request in one of the following situations: 

• For access to an entry-sequenced data set. 

• For access to an entry-sequenced data set via a path. 

• With control interval access. 

84(54) You specified OPTCD= LOC in one of the following situations: 

• For a PUT request. 

• In a request parameter list in a chain of request parameter lists. 

• For UBF processing. 

Figure 8 (Part 3 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 3 8(8) Condition 


92(5C) 


96(60) 


100(64) 


104(68) 


You issued a sequential GET request without having caused 
VSAM to be positioned for it, or you changed from addressed 
access to keyed access without causing VSAM to be positioned for 
keyed-sequential retrieval; there was no positioning established for 
sequential PUT insert for a relative record data set, or you 
attempted an illegal switch between forward and backward 
processing. 

You issued a PUT for update or an ERASE without a previous 
GET for update, or a PUTIX without a previous GET1X. 

You attempted to change the prime key or key of reference while 
making an update. 

You attempted to change the length of a record while making an 
addressed update. 

The RPL options are either invalid or conflicting in one of the 
following, ways: 

• SKP was specified and either KEY was not specified or BWD 
was specified. 

• BWD was specified for CNV processing. 

• FWD and LRD were specified. 

• Neither ADR, CNV, nor KEY was specified in the RPL. 

• BFRNO is invalid (less than 1 or greater than the number of 
buffers in the pool). 

• WRTBFR, MRKBFR, or SCHBFR was issued, but either 
TRANSID was greater than 31 or the shared resource option 
was not specified. 

• ICI processing was specified, but a request other than a GET 
or a PUT was issued. 

• MRKBFR MARK = OUT or MARK=RLS was issued but 
the RPL did not have a data buffer associated with it. 

• The RPL specified WA1TX, but the ACB did not specify LSR 
or GSR. 


Figure 8 (Part 4 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 


20 MVS/XA VSAM Administration: Macro Instruction Reference 




Reason Code 
(RPLERRCD) 

When Register 
15 ~ 8(8) Condition 

108(6C) RECLEN specified was larger than the maximum allowed, equal to 
0, or smaller than the sum of the length and the displacement of 
the key field; RECLEN was not equal to record (slot) size specified 
for a relative record data set. The automatic increase in the record 
size of an upgrade index for the base cluster may cause an incorrect 
RECLEN specification. 

112(70) KEYLEN specified was too large or equal to 0. 

116(74) During initial data set loading (that is, when records arc being 
stored in the data set the first time it's opened), GET, POINT, 
ERASE, direct PUT, skip-sequential PUT, or PUT with 
OPTCD= UPD is not allowed. For initial loading of a relative 
record data set, the request was other than a PUT insert. 

120(78) The request was operating under an incorrect TCB. For example, 
an end-of-volume call or a GETMA1N would have been necessary 
to complete the request, but the request was issued from a job step 
other than the one that opened the data set. The request can be 
resubmitted from the correct task, if the new request reestablishes 
positioning. 

124(7C) A request was cancelled for a user JRNAD exit. 

132(84) An attempt was made in locate mode to retrieve a spanned record. 

136(88) You attempted an addressed GET of a spanned record in a 

key-sequenced data set. 

| 140(8C) The spanned record segment update number is inconsistent. 

144(90) Invalid pointer (no associated base record) in an alternate index. 

148(94) The maximum number of pointers in the alternate index has been 

exceeded. 

152(98) Not enough buffers are available to process your request (shared 
resources only). 

156(9C) An invalid control interval was detected during keyed processing, or 
an addressed GET UPD request failed because the control interval 
flag was on, or an invalid control interval or index record was 
detected. The RPL contains the invalid control interval's RBA. 

Figure 8 (Part 5 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 

When Register 

15 - 8(8) Condition 

160(A0) One or more candidates were found that have a modified buffer 

marked to be written. The buffer was left in write status with valid 
contents. With this condition, it is possible to have other buffers 
invalidated or found under exclusive control. 

164(A4) One of the following invalid options was specified for a 
CNVTAD/MNTACQ/ACQRANGE request: 

• Generic key (GEN) 

• Load mode 

• Path processing 

• User buffers (UBF) with LSR/GSR 

• Key-sequenced data set, but not key processing (KEY) 

• Entry-sequenced data set, but not address processing (ADR) 

• Relative record data set, but not key processing (KEY) 

• RPL is chained 

• Key-sequenced data set has single-level imbedded index 

168(A8) One of the following user parameter list errors was detected for 
CNVTAD/MNTACQ/ACQRANGE request: 

• No user parameter list is specified (RPLARG = 0) 

• Argument count is zero for CNVTAD/MNTACQ request 

• Ending argument is less than starting argument for 
ACQRANGE request 

• Parameter list not on word boundary 

i72(AC) ACQUIRE error returned by SVC 126 for 
MNTACQ/ACQRANGE request. 

176(B0) Staging failure for MNTACQ/ACQRANGE request. 

180(B4) RBA/volumc error for MNTACQ/ACQRANGE request. 

(Required volume not mounted or specified RBA(s) not on 
mounted volume.) 

Figure 8 (Part 6 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

184(B8) Catalog errors returned from SVC 126 for CNVTAD request. 

188(BC) Storage for ACQUIRE ECBs (subpool 241) is not available. 

192(C0) Invalid relative record number. 

196(C4) You issued an addressed request to a relative record data set. 

200(C8) You attempted addressed or control interval access through a path. 

204(CC) PUT insert requests are not allowed in backward mode. 

208(D0) The user has issued an ENDREQ macro instruction against an 
RPL that has an outstanding WAIT against the ECB associated 
with the RPL. This can occur when an ENDREQ is issued from a 
STAE or ESTAE routine routine against an RPL that was started 
before the abend. No ENDREQ processing has been done. 

212(D4) During control area split processing, a condition exists that prevents 
the split of the index record. Index control interval size may need 
to be increased. 

224(E0) MRKBFR OUT was issued for a buffer with invalid contents. 

228(E4) Caller in cross-memory mode is not in supervisor state or RPL of 
caller in SRB or cross-memory mode docs not specify SYN 
processing. 

232(E8) UPAD error; ECB was not posted by user in cross-memory mode. 

236(EC) Validity check error for SHAREOPTIONS 3 or 4. 

240(F0) For shared resources, one of the following is being performed: (a) 
an attempt is being made to obtain a buffer in exclusive control, (b) 
a buffer is being invalidated, or (c) the buffer use chain is changing. 
For more detailed feedback, reissue the request. 

244(F4) Register 14 stack size is not large enough. 

248(F8) Register 14 return offset went negative. 

252(FC) Record mode processing is not allowed for a linear data set. 

253(FD) VERIFY is not a valid function for a linear data set. 

Figure 8 (Part 7 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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When the search argument you supply for a POINT or GET request is greater 
than the highest key in the data set, the reason code in the feedback area depends 
on the RPL's OPTCD values, as shown in the table below: 


Request 

RPLs OPTCD 

Reason Code (RPLERRCD) 

Type 

Options 

When Register 15*8(8) 
Decimal Hexadecimal 

POINT 

GEN.KEQ 

16 

X f 10’ 

POINT 

GEN.KGE 

4 

X r 4’ 

POINT 

FKS.KEQ 

16 

X'lO* 

POINT 

FKS.KGE 

4 

X’4' 

GET 

GEN.KEQ,DIR 

16 

X'lO* 

GET 

GEN.KGE,DIR 

16 

X’lO' 

GET 

FKS.KEQ.DIR 

16 

X'lO* 

GET 

FKS.KGE,DIR 

16 

X f 10 f 

GET 

GEN.KEQ.SKP 

16 

X f 10 f 

GET 

GEN.KGE.SKP 

4 

X f 4 f 

GET 

FKS.KEQ.SKP 

16 

X f 10* 

GET 

FKS.KGE.SKP 

4 

X *4* 


Positioning Following Logical Errors 

VSAM is unable to maintain positioning after every logical error. Whenever 
positioning is not maintained following an error request, you must reestablish it 
before processing resumes. 

Positioning may be in one of four states following a POINT or a direct request 
that encountered a logical error: 

Yes VSAM is positioned at the position in effect before the request in error 
was issued. 

No VSAM is not positioned, because no positioning was established at the 
time the request in error was issued. 

New VSAM is positioned at a new position. 

U VSAM is positioned at an unpredictable position. 

The following table shows which positioning state applies to each reason code 
listed for sequential, direct, and skip-sequential processing. "N/A" indicates that 
the reason code is not applicable to the type of processing indicated. Figure 9 on 
page 25 lists these codes and their meanings. 
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Reason Code 
(RPLERRCD) 
When Register 
15 = 8(8) 


Decimal 

Hexadecimal 

Sequential 

Direct 

Skip-Sequential 

4 

X V 

Yes 

N/A 

Yes 

8 

X ’ 8* 1 

Yes 

No 

New 

12 

x’c* 

Yes 

N/A 

Yes 

16 

X’10' 

No 

No 

No 

20 

XM4* 

U 

No 2 

No 2 

24 

X * 18 f 

Yes 

No 

No 

28 

X f 1C* 

Yes 

No 

Yes 

32 

X'20 f 

No 

No 

N/A 

36 

X'24 f 

Yes 

No 

New 

40 

X’28 f 

Yes 

No 

No 

44 

X'2C ? 

Yes 

New 

Yes 

64 

X’40’ 

No 

No 

No 

68 

X *44 T 

Yes 

Yes 

Yes 

72 

X f 48 f 

Yes 

Yes 

Yes 

76 

X’4C f 

Yes 

Yes 

Yes 

80 

X f 50* 

Yes 

Yes 

Yes 

84 

X'54' 

Yes 

Yes 

Yes 

88 

X * 58 f 

Yes 

Yes 

Yes 

92 

X'SC' 

Yes 

Yes 

Yes 

96 

X * 60 f 

Yes 

Yes 

Yes 

100 

X f 64 f 

Yes 

Yes 

Yes 

104 

x’68’ 

Yes 

New 

Yes 

108 

X^C* 

Yes 

New 

Yes 

112 

X * 70 f 

Yes 

Yes 

Yes 

116 

X'74* 

Yes 

Yes 

Yes 

120 

x^s* 

Yes 

No 

No 

124 

X' 7C f 

No 

No 

No 

132 

X 1 84' 

Yes 

New 

Yes 

136 

X 1 88 * 

No 

No 

N/A 

140 

X ’ 8C* 

Yes 

New 

Yes 

144 

X'90' 

Yes 

Yes 

Yes 

148 

X ’ 94' 

Yes 

Yes 

Yes 

152 

X ' 98* 

Yes 

No 

No 

156 

X ’ 9C* 

Yes 

No 

No 

160 

X 1 A0* 

N/A 

No 

N/A 

192 

X’CO* 

Yes 

Yes 

Yes 

196 

X * C4* 

Yes 

Yes 

Yes 


Figure 9 (Part 1 of 2). Positioning States of Reason Codes Listed for Sequential, 
Direct, and Skip-Sequential Processing 
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Reason Code 
(RPLERRCD) 
When Register 
15-8(8) 


Decimal 

Hexadecimal 

Sequential 

Dircet 

Skip-Sequential 

200 

X f C8' 

Yes 

Yes 

Yes 

204 

X'CC* 

Yes 

Yes 

Yes 

208 

X'DO* 

Yes 

Yes 

Yes 

224 

X’EO' 

N/A 

No 

N/A 

228 

X 1 E4 * 

No 

No 

No 

232 

X’E8* 

No 

No 

No 

236 

X'EC’ 

No 

No 

No 

240 

X f F0 f 

Yes 

Yes 

Yes 


1 A subsequent GET SEQ will retrieve the duplicate record; however, a 
subsequent GET SKP for the same key will get a sequence error. In a 
relative record data set, a subsequent PUT SEQ positions to the next slot 
(whether the slot is empty or not). 

2 PUT UPD, DIR or UPD, SKP retains positioning. The RPL contains an 
RDA that could not be obtained for exclusive control. 

Figure £ (Part 2 of 2 }» Positioning’ States' of Reason Cades Listed for Sequential, 
Direct, and Skip-Sequential Processing 


Reason Code (Physical Errors) 

If a physical error occurs and you have no SYNAD routine (or the SYNAD exit 
is inactive), VSAM returns control to your program following the last executed 
instruction. The return code in register IS indicates a physical error (12), and the 
feedback area in the request parameter list contains a reason code identifying the 
error; the RPL message area contains more details about the error. Register l 
points to the request parameter list. The RBA field in the request parameter list 
gives the relative byte address of the control interval in which the physical error 
occurred. Figure 10 gives the reason codes in the feedback area and explains 
what each indicates. 
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Reason Code 
(RPLERRCD) 
When Register 
15“ 12(0C) 

4(4) 

8 ( 8 ) 

12(C) 

16(10) 

20(14) 

24(18) 


Condition 

Read error occurred for a data set. 

Read error occurred for an index set. 
Read error occurred for a sequence set. 
Write error occurred for a data set. 
Write error occurred for an index set. 
Write error occurred for a sequence set. 


Figure 10. Physical Error Reason Codes in the Feedback Area of the Request 
Parameter List 


Figure 11 gives the format of a physical error message. ITie format and some of 
the contents of the message are purposely similar to the format and contents of 
the SYNADAF message, which is described in Data Administration: Macro 
Instruction Reference. 


Fidd 

Bytes 

Length 

Discussion 

Message 

Length 

0-1 

2 

Binary value of 128 


2-3 

2 

Unused (0) 

Message 

Length - 4 

4-3 

2 

Binary value of 124 
(provided for compatibility 
with SYNADAF Message) 


6-7 

2 

Unused (0) 

Address of 

I/O Buffer 

8-11 

4 

The I/O buffer associated 
with the data where 
the error occurred 

The rest of the message i 

is in printable format 

Date 

12-16 

5 

YYDDD (year and day) 


17 

1 

Comma (,) 

Time 

18-25 

8 

HHMMSSTH (hour, minute, 
second, and tenths and 
hundredths of a second 

Figure 11 (Part 1 

of 4). 

Physical Error Message Format 
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Field 

Bytes 

Length 

Discussion 


26 

1 

Comma (,) 

RBA 

27-34 

8 

Relative byte address of the 
record where 




the error occurred 


35 

1 

Comma (,) 

Component 

TYPE 

36-41 

6 

"DATA" or "INDEX" 


42 

1 

Comma (,) 

Volume Serial 

43-48 

6 

Volume serial number of the 

Number 



volume where 
the error occurred 


49 

1 

Comma (,) 

Job Name 

50-57 

8 

Name of the job where 
error occurred 


58 

1 

Comma (,) 

Step Name 

59-66 

8 

Name of the job step in 
which error occurred 


67 

1 

Comma (,) 

Unit 

68-70 

3 

The unit, CUU (channel and 

unit), where 

the error occurred 


71 

1 

Comma (,) 

Device Type 

72-73 

2 

The type of device where 
the error 




occurred (always DA for 
direct access) 


74 

1 

Comma (,) 

ddnamc 

75-82 

8 

The ddname of the DD 
statement defining the data 
set where the 
error occurred 


83 

1 

Comma (,) 


Figure 11 (Part 2 of 4). Physical Error Message Format 
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Field 


Bytes Length Discussion 


Channel 


Message 


84-89 

6 

The channel command that 
caused the error in the first 
two bytes, followed by "_OP 

90 

1 

Comma (,) 

91-105 

15 

Messages are divided 
according to ECB condition 
codes: 


XMl' "INCORR LENGTH" 
"UNIT EXCEPTION" 
"PROGRAM CHECK" 
"PROTECTION CHK" 
"CHAN DATA CHK" 
"CHAN CTRL CHK" 
"INTFCE CTRL CHK" 
"CHAINING CHK" 
"UNIT CHECK" 


If the type of unit check can 
be detennined, the 'UNIT CHECK' 
message is replaced by one of 
by one of the following: 


"CMD REJECT" 

"INT REQ" 

"BUS OUT CK" 

"EQP CHECK" 

"DATA CHECK" 

"OVER RUN" 

"TRACK CGNDCK” 
"SEEK CHECK" 
"COUNT DATA CHK" 
"TRACK OVERRUN" 
"CYLINDER END" 

"NO RECORD FOUND" 
"FILE PROTECT" 
"MISSING A.M " 
"OVERFLINCP" 


X’48 f "PURGED REQUEST" 
X’4A* "I/O PREVENTED" 

X *4F T "R.HA.RO. ERROR" 


For any other ECB condition code: 

"UNKNOWN COND." 


Figure 11 (Part 3 of 4). Physical Error Message Format 
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Field 

Bytes 

Length 

Discussion 


106 

1 

Comma (,) 

Physical 

Direct Access 
Address 

107-120 

14 

BBCCHHR (bin, cylinder, 
head, and record) 


121 

1 

Comma (,) 

Access 

Method 

122-127 

6 

"VSAM” 


Figure 11 (Part 4 of 4). Physical Error Message Format 


Return Codes from Macros Used to Share Resources among Data Sets 

VSAM has a set of macros that enables you to share I/O buffers, I/O related 
control blocks, and channel programs among VSAM data sets. 

| Return Codes from BLDVRP 

VSAM returns a code in register 15 that indicates whether the BLDVRP request 
was successful: 

Return 

Code Condition 

0(0) VSAM completed the request. 

| 4(4) The requested data resource pool or index resource pool already exists 

| in the address space (LSR) or in the system protect key (GSR). 

8(8) There is not enough virtual storage space to satisfy the request. 

GETMAIN or ESTAE failed. 

12(C) Buffers cannot be fixed in real storage. PAGEFIX failed. 

16( 10) TYPE = GSR is specified but the program that issued BLDVRP is 
not in supervisor state with protection key 0 to 7. 

20(14) STRNO is less than 1 or greater than 255. 

24(18) BUFFERS is specified incorrectly. A size or number is invalid. 

28(1C) The requested resource pool is invalid. A SHRPOOL value greater 

than 15 was specified. 
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32(20) 


The resource pool already exists above 16 megabytes and the request 
was for storage below 16 megabytes, or the resource pool already 
exists below 16 megabytes and the request was for storage above 16 
megabytes. 

36(24) BLDVRP was issued to build an index resource pool but the required 
corresponding data resource pool does not exist. 

Return Codes from DLVRP 

VS AM returns a code in register 15 that indicates whether the DLVRP request 
was successful: 

Return 

Code Condition 

0(0) VSAM completed the request. 

4(4) There is no resource pool to delete. 

8(8) There is not enough virtual storage space to satisfy the request. 
GETMAIN or ESTAE failed. 

12(C) There is at least one open data set using the resource pool. 

16(10) TYPE = GSR is specified, but the program that issued DLVRP is not 

in supervisor state with protection key 0 to 7. 


Return Codes from End-of-Volume 

End-of-volume returns the following codes in register 15: 

Return 

Code Condition 

0(0) Successful. 

4(4) The requested volume could not be mounted. 

8(8) The requested amount of space could not be allocated. 

12(C) I/O operations were in progress when end-of-volume was requested. 

16(10) The catalog could not be updated. 
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Chapter 2. VSAM Macro Formats and Examples 


This chapter contains macro instruction formats and examples. 

The macros that work at assembly time allow you to specify subparametcr values 
as absolute numeric expressions, character strings, codes, and expressions that 
generate valid relocatable A-type address constants. The macros that work at 
execution allow you also to specify these values as: 

• Register notation, where the expression designating a register from 2 through 
12 is enclosed in parentheses; for example, (2) and (REG), where REG is a 
label equated to a number from 2 through 12 

• An expression of the form (S.scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form 

• An expression of the form (*,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form, and the 
address specified by scon is indirect—that is, it gives the location of the area 
that contains the value for the subparameter. 

For most programming applications, you can conveniently use register notation 
or absolute numeric expressions for numbers, character strings for names, and 
register notation or expressions that generate valid A-type address constants for 
addresses. Appendix C, “Operand Notation” on page 181, gives all the ways of 
coding each parameter for the macros that work at execution time. 

You can write a reentrant program only with execution-time macros. 

Appendix B, “List, Execute, and Generate Forms of Macros” on page 171, 
describes alternative ways of coding these macros for reentrant programs. This 
chapter describes the standard form of these macros. 
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ACB 


I ACB Macro (Generate an Access Method Control Block at Assembly 
I Time) 


The format of the ACB macro is: 


[label 


ACB 


[AM® VSAMJ 
{,BSTRNO = number] 

|,BUFND = number j 
[,BUFNI • number] 

|,BUFSP = number] 

1,CATALOG = YES|NO| 

(,CRA = SCRA|UCRA| 

|,DDNAME- ddname] 

|,EXLST = address] 

|,MACRF - (IADRIf.CNVII. KEYI 
I.CFXI NFXI 
L PDN IDSNI 
LDFRI NPH 
I,DIRI|,SE2I!,SKP| 

|,ICI|NCI| 

l,|N|(,OUTl 

(,NIS|SISl 

I. NRM IAIXI 

L NRSI RSTI 

1.NSR1LSRIGSR1 

(,NUB|LBF|)| 

|,MAREA = address | 

IJNILEN = number] 

(,PASS\VD = address] 

|,RMODE3I = f ALL1BUFF1CB1 NONE) I 
f,SHRPOOL= {ft\number}\ 
j,STRNO = number] 


/ 


| Note: r rhe RMODE31 parameter replaces the AMODE31 subparameter shown 

| in previous releases. 

Values for ACB macro subparameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-typc address constants. 

label 

is 1 to 8 characters that provide a symbolic address for the access method 
control block that is assembled and also, if you omit the DDNAME 
parameter, serves as the ddname. 

AM = VS AM 

specifies that the access method using this control block is VSAM. 
BSTRNO = number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the 
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object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can influence performance. 
The VSAM control blocks for the set of strings specified by BSTRNO are 
allocated on contiguous virtual storage, whereas this is hot guaranteed for 
the strings allocated by dynamic extension. 

BUFND = number 

specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at least 2, because the default for STRNO is 1). The number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. Note, however, 
that minimum buffer specification does not provide optimum sequential 
processing performance. Generally, the more data buffers specified, the 
better the performance. Note also that additional data buffers will benefit 
direct inserts or updates during control area splits and will benefit spanned 
record accessing. For more information, see “Optimizing Performance” in 
VSAM Administration Guide. 

BUFNI = number 

specifies the number of I/O buffers VSAM is to use for transmitting the 
contents of index entries between virtual and auxiliary storage for keyed 
access. A buffer is the size of a control interval in the index. The 
minimum number is the number specified for STRNO (if you omit 
STRNO, BUFNI must be at least 1, because the default for STRNO is 1). 
You can supply the number by way of the JCL DD AMP parameter as 
well as by way of the macro. 'Hie default is the minimum number 
required. 

Additional index buffers will improve performance by providing for the 
residency of some or all of the high-level index, thereby minimizing the 
number of high-level index records to be retrieved from DASD for 
key-direct processing. For more information, see “Optimizing 
Performance” in VSAM Administration Guide. 

BUFSP = number 

specifics the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEF INE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• The amount specified in the catalog (BUFFERSPACE), 

• The amount determined from BUFND and BUFNI, or 


Chapter 2. VSAM Macro Formats and Examples 35 



The minimum storage required to process the data set with its specified 
processing options 




If BUFSP is specified and the amount is smaller than the minimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not fewer than the minimum number. Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not fewer than 1 more than the minimum number. 

Then, if required, the number of data buffers is decreased to not fewer 
than the minimum number. If still required, 1 more is subtracted from 
the number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to fewer than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. The bufferspace must not exceed 
16776704. 

CATALOG = YES I NO 

specifies whether a catalog is being opened as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, etc). Your program must be 
APF-authorizcd to process a catalog as a data set. To open a password 
protected catalog for processing with VSAM macros, you must supply its 
master password. When CATALOG - YES is coded, the catalog must be 
processed with an SVC designed for that purpose. (Access method services, 
for example, processes catalogs with SVC 26.) The request macros are 
invalid for processing a catalog “as a catalog.” VSAM users should alter the 
contents of a catalog only by access method services commands. 

CRA = SCRA|UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
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(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME= ddname 

is 1 to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the label or by way of the MODCB 
macro before opening the data set. MODCB is described later in this 
chapter. 

EXLST = address 

specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1 or the label of an area you supplied to GENCB for 
the exit list. Omitting this parameter indicates that you have no exit 
routines. Exit routines are described in “User-Written Exit Routines” in 
Data Facility Product: Customization. 

MACRF = (IADR11.CNVH. KEYI 
I.CFXI NFXI 
I. PDN IPSN1 
LPFR1 NDF1 
I.PlRIf.SEOll.SKPl 
MCIINC1I 
l,IN||,OUT| 

LMS1SISI 

L NRM 1AIXI 

I.NRSIRST1 

|,NSR|LSR|GSR| 

LNUB1UBFB 

specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
data set. You must specify all the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
Figure 12 on page 38 gives the subparameters; each group of 
subparameters has a default value (indicated by underlining). You may 
specify subparameters in any order. You may specify both ADR and KEY 
to process a key-sequenced data set. You may specify both DIR and SEQ; 
with keyed access, you may specify SKP as well. If you specify OUT and 
want merely to retrieve some records as well as update, delete, or insert 
others, you need not also specify IN. 

Note: The RMODE31 parameter replaces the AMODE31 subparameter 
shown in previous releases. 


Chapter 2. VS AM Macro Formats and Examples 37 



ACB 


Option Meaning 

ADR Addressed access to a key-sequenced or an entry-sequenced data 

set; RBAs are used as search arguments and sequential access is by 
entry sequence. 

CNV Access is to the entire contents of a control interval rather than to 

an individual data record. If the data set is password protected, 
you must supply the address of the control or higher-level 
password in the ACB PASSWD parameter. 

KEY Keyed access to a key-sequenced or relative record data set; keys 

or relative record numbers are used as search arguments and 
sequential access is by key or relative record number. 

CFX Control blocks and I/O buffers are to be fixed in real storage; 

MACRF = ICI must also be specified. 

NFX Control blocks and I/O buffers are fixed in real storage only 

during I/O operations. 

DDN Subtask shared control block connection is based on common 

ddnames. 

DSN Subtask shared control block connection is based on common 

data set flames. 

DFR With shared resources, writes for direct PUT requests are deferred 

until the WRTBFR macro is issued or until VSAM needs a buffer 
to satisfy a GET request; deferring writes saves I/O requests in 
cases where subsequent requests can be satisfied by the data 
already in the buffer pool. 

NDF Writes are not to be deferred for direct PUTs. 

DIR Direct access to a key-sequenced, entry-sequenced, or a relative 

record data set. 

SEO Sequential access to a key-sequenced, entry-sequenced, or a 

relative record data set. 

SKP Skip-sequential access to a key-sequenced or a relative record data 

set; used only with keyed access in a forward direction. 

ICI Processing is limited to improved control interval processing; 

access is faster because fewer processor instructions are executed. 

NCI Processing other than improved control interval processing. 

IN Retrieval of records of a key-sequenced, entry-sequenced, or a 

relative record data set; (not allowed for an empty data set). If the 
data set is password protected, you must supply the address of the 
read or higher-level password in the ACB PASSWD parameter. 

Figure 12 (Part 1 of 2). MACRF Options 
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Option Meaning 

OUT Storage of new records in a key-sequenced, entry-sequenced, or 

relative record data set (not allowed with addressed access to a 
key-scquenccd data set); update of records in a kcy-scquenced, 
entry-sequenced, or relative record data set; deletion of records from a 
key-sequenced data set or relative record data set. 

If the data set is password protected, you must supply the address of 
the update or higher-level password in the ACB PASSWD parameter. 

NIS Normal insert strategy. 

SIS Sequential insert strategy (split control intervals and control areas at 

the insert point rather than at the midpoint when doing direct PUTs); 
although positioning is lost and writes arc done after each direct PUT 
request, SIS allows more efficient space usage when direct inserts are 
clustered around certain keys. 

NRM The object to be processed is the one named in the specified ddname. 

AIX 'Hie object to be processed is the alternate index of the path specified 

by ddname, rather than the base cluster via the alternate index. 

NRS Data set is not reusable. 

RST Data set is reusable (high-used RBA is reset to 0 during OPEN). If 
the data set is password protected, you must supply the address of the 
update or higher-level password in the ACB PASSWORD parameter. 

NSR Nonsharcd resources. 

LSR Local shared resources. Each address space may have up to 16 index 
resource pools and 16 data resource pools independent of other 
address spaces. Unless you arc using the default, SIIRPOOL = 0, you 
must specify the StIRPOOL parameter to indicate which resource 
pool you are using. Specifying LSR will cause a data set to use the 
local resource pool built by the BLDVRP macro. If an index 
resource pool exists at the time an OPEN macro is issued, the index 
for a key-scquenced data set will be connected to the index resource 
pool. 

GSR Global shared resources; all address spaces may have local and global 
resources pools, where tasks in an address space with a local resource 
pool may use either the local resource pool or the global resource 
pool. 

NUB Management of I/O buffers is left up to VSAM. 

UBF Management of I/O buffers is left up to the user; the work area 

specified by the RPL (or GENCB) AREA parameter is, in effect, the 
I/O buffer—VSAM transmits the contents of a control interval directly 
between the work area and direct access storage; valid when 
OPTCD = MVE and MACRF = CNV are specified; when ICI is 
specified, UBF is assumed. 

Figure 12 (Part 2 of 2). MACRF Options 
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MAREA = address 

specifies the address of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. See “OPEN/CLOSE Message Area for 
Multiple Reason or Warning Messages” on page 7 for more information. 

MLEN = number 

specifies the length of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. Default = 0; maximum = 32K. See 
“OPEN/CLOSE Message Area for Multiple Reason or Warning Messages” 
on page 7 for more information. 

PASSWD = address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the field pointed to contains the length (in binary) of the 
password (maximum of 8 bytes). Zero indicates that no password is 
supplied. If the data set is password protected and you don't supply a 
required password in the access method control block, VSAM will give the 
console operator the opportunity to supply it when you open the data set. 

RMODE3I = [ALL|BUFF|CB|NONE| 

specifics where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 

The values specified by the RMODE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
changing these values has no effect on the residency of the control blocks 
and I/O buffers. 

ALL 

both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 

only VSAM I/O buffers are to be obtained above 16 megabytes. 

CB 

only VSAM control blocks are to be obtained above 16 megabytes. 
NONE 

both I/O buffers and VSAM control blocks arc to be built below 16 
megabytes. This is the default. 

Note: In previous releases, the MACRF subparameter AMODE31 
specified that I/O buffers were to be obtained above 16 megabytes and that 
the caller was running in 31-bit addressing mode. The RMODE31 
parameter replaces the AMODE3I subparameter and the two are mutually 
exclusive. If both the AMODE31 subparameter and the RMODE31 
parameter are specified within the same program, AMODE31 is ignored. 

SHRPOOL = {rtumber\ti) 

identifies which LSR pool is to be connected to the ACB. This parameter 
is valid only when MACRF = LSR is also specified. The identification 
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number of the shared pool must be a number from 0 to 15. The default is 

0 . 

STRNO = number 

specifies the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. The default is 1. A request is defined 
by a given request parameter list or chain of request parameter lists. See 
“RPL Macro (Generate a Request Parameter List at Assembly l ime)” on 
page 126 and “GENCB Macro (Generate a Request Parameter List at 
Execution Time)” on page 80 for information on request parameter lists. 
When records are loaded into an empty data set, the STRNO value in the 
access method control block must be 1. 

VSAM dynamically extends the number of strings as they are needed by 
concurrent requests for this ACB. This automatic extension can influence 
performance. The VSAM control blocks for the set of strings specified by 
STRNO are allocated on contiguous virtual storage, but this is not 
guaranteed for the strings allocated by dynamic extension. Dynamic string 
addition cannot be done when using the following options: 

• Load mode 

• 1CI 

• LSR or GSR 

For STRNO, you should specify the total number of request parameter 
lists or chains of request parameter lists that you are using to define 
requests. (VSAM needs to remember only one position for a chain of 
request parameter lists.) However, each position beyond the minimum 
number that VSAM needs to be able to remember requires additional 
virtual storage space for: 

• A minimum of one data I/O buffer and, for keyed access, one index 
I/O buffer (the size of an I/O buffer is the control interval size of a data 
set) 

• Internal control blocks and other areas 
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Example 1: ACB Macro 


In this example, the ACB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. The access method control 
block generated by this example is built when the program is assembled. 

BLOCK ACB AM=VSAM,BUFND=4, BLOCK gives symbolic 

BUFNI=3, address of the access 

BUFSP=19456, method control block. 

DDNAME=DATASETS, 

EXLST=EXITS, 

MACEF=(KEY,DIR,SEQ,OUT), 

PASSWD=FIELD, 

STRN0=2 

FIELD DC FL1 * 6*,C'CHANGE' The update password: 

CHANGE has 6 characters. 


The ACB macro's parameters arc: 

• BUFND specifies four I/O buffers for data; BUFNI specifies three I/O 
buffers for index entries; .and BUFSP specifics 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and control intervals of index entries that arc 1024 bytes. 

• DDNAME specifics that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifies that the exit list associated with this access method control 
block is named EXITS. 

• MACRF specifics keyed-direct and keyed-sequential processing for both 
insertion and update. 

• PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itself. 

• STRNO specifies that two requests will require concurrent positioning. 
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| Example 2: ACB Macro 

| In this example, the ACB macro is used to identify a data set to be opened and 

| to specify the types of processing to be performed. An LSR pool is connected to 

| the data set. The access method control block generated by this example is built 

| when the program is assembled. The caller requests that the VSAM control 

| blocks and I/O buffers be obtained above 16 megabytes if possible. 

BL0CK2 ACB AM=VSAM, 

DDNAME=DATASETS, 

EXLST=EXITS, 

MACRF=(KEY,DIR, 

LSR,SEQ,OUT), 

PASSWD=FIELD, 

RM0DE31=ALL, 

SHRP00L=1 

| FIELD DC FLl'6',C*CHANGE* The update password: 

j CHANGE has 6 characters. 

The ACB macro's parameters are: 

• DDNAME specifics that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifics that the exit list associated with this access method control 
block is named EXITS. 

• MACRF specifies keyed-direct and keyed-sequential processing for both 
insertion and update. LSR indicates that the I.SR pool created by BLDVRP 
is to be connected to the data set. 

• PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itself. 

| • RMODE31 = ALL specifies that you want both VSAM control blocks and 

| I/O buffers to reside above 16 megabytes. 

• SHRPOOL specifies that the LSR pool with the identification number of 1 is 

| to be used. However, if an index resource pool exists at the time the OPEN 

| macro is issued, the index for the key-sequenced data set will be connected to 

| the index resource pool. 


BL0CK2 gives symbolic 
address of the access 
method control block. 
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ACQRANGE Macro (Stage Data) 

The format of the ACQRANGE macro is: 

~[label\ [ACQRANGE [ RPL = address 
RPL = address 

specifies the address of the RPL that identifies your open data set and your 
argument range. RPL parameters that have meaning for ACQRANGE are 
as follows: 

ACB = address 

identifies your VSAM data set. 

ARG = address 

identifies your starting and ending arguments. Address points to a 
parameter list, aligned on a fullword boundary as follows: 

KEY-SEQUENCED DATA SET 

Offset Length Contents 

0 4 Feedback area: Address 

of an ECB WAIT list 

4 K Starting full argument 

(K = key length) 

4 + K K (K = key length) 

ENTRY-SEQUENCED DATA SET OR RELATIVE RECORD 
DATA SET 

Offset Length Contents 

0 4 Feedback area: Address 

of an ECB WAIT list 

4 4 Starting RBA/RRN 

8 4 Ending RBA/RRN 

The maximum number of argument pairs you may specify is one. 

OPTCD = ({ADRjKEY} 

,{ASY|SYN) 

,{KEQ|KGE) 

,FKS) 

ADR is valid for an entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 
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KEY is valid for key-sequenced data set and relative record data set, 
error for entiy-sequenced data set. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of event 
control blocks (ECB) (in standard WAIT list format) which you may 
use in place of the RPLECB field. 

GEN is not supported; if specified, it will give an error indication. 

All other OPTCD subparameters are not applicable, and, if specified, 
are ignored with no error indication. 

Because your request may result in the staging of numerous cylinders, a single 
ECB is not sufficient for an asynchronous ACQRANGE request. The RPLECB 
field is inoperative for the ACQRANGE interface. Upon return from an 
asynchronous ACQRANGE, the feedback area of the ACQRANGE parameter 
contains the address of a standard ECB WAIT list. You must then use this list 
in conjunction with either the WAIT macro or the EVENTS macro of MVS. 

An asynchronous request must conclude with cither CHECK, ENDREQ, or 
CLOSE. ITic parameter list cannot be reused until the CHECK, ENDREQ, or 
CLOSE is completed. 

At the conclusion of this macro, the RPL is disconnected. Any positioning in 
effect prior to execution of ACQRANGE will be lost. You may have to 
reposition. Chained RPLs are not supported by this macro. 
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BLDVRP Macro (Build VSAM Resource Pool) 


The format of the BLDVRP macro is*. 


BLDVRP 

BUFFERS = {size{ number) jize{ number ),...) 


(,FIX = {BFR|IOB|(BFR,IOB)}| 


[JKEYLEN = length] 


I.RMODE31 = {ALLjBUFFICBINONEll 


[,SHRPOOL= [ti\number}\ 


|,MODE={24|3?}| 


,STRNO = number 


|,TYPE» {LSRf,DATA|INDEX| | GSR}| 


Note: The RMODE31 parameter replaces the LOC= BELOW|ANY parameter 
shown in previous releases. 

The BLDVRP macro has a standard form and list and execute forms. The 
standard form builds a parameter list and passes control to VSAM to build the 
resource pool. The list and execute forms are described in Appendix B, “List, 
Execute, and Generate Forms of Macros” on page 171. 

BUFFERS = ( size{number)ySize(number ),...) 

specifies the size and number of buffers in each buffer pool in the resource 
pool. The number of buffer pools in the resource pool is implied by the 
number of size(numbcr) pairs you specify. 

When you process a key-sequenced data set, the index component, as well 
as the data component, shares the buffers of a buffer pool. When you use 
an alternate index to process a base cluster, the components of the alternate 
index and the base cluster share buffers. The components of alternate 
indexes in an upgrade set share buffers. Buffers of the appropriate size and 
number must be provided for all these components. Each component uses 
the buffer pool with buffers either the required size or larger. 

size 

is 512, 1024, 2048, 4096, and then in increments of 4096 to a 
maximum of 32K bytes. 

number 

is at least 3. 

Size times number must be less than 16 megabytes. 

FIX= (BFR)IOB](BFR,IOB)} 

specifies that I/O buffers (BFR), or I/O-relatcd control blocks (IOB), or 
both, are to be fixed in real storage. With GSR, IOB includes channel 
programs. If the program that issues BLDVRP with FIX specified is not 
authorized to fix areas in real storage, FIX is ignored. A program is 
authorized if it is in supervisor state with protection key 0 to 7, or has been 
link-edited with authorization (the authorized program facility is described 
in Supervisor Services and Macro Instructions). 


46 MVS/XA VSAM Administration: Macro Instruction Reference 







BLDVRP 


Note: If FIX is specified, DLVRP must be issued by the same task that 
issues BLDVRP. 

KEYLEN = length 

specifies the maximum key length of the data sets that are to share the 
resource pool. The default is 255. The keys whose lengths must be 
provided for are the prime key of each key-sequenced data set and the 
alternate key of each alternate index that is used for processing or is being 
upgraded. If none of the data sets is keyed, specify 0. 

RMODE31 * fALLIBUrriCBI NONE) 

specifies the storage residence location of the buffers and I/O related control 
blocks of the LSR pool identified with the SIIRPOOL keyword. 

Ihe RMODE31 parameter tells the VSAM OPEN routines where to 
obtain storage for the I/O related control blocks and I/O buffers. 

Therefore, the only time the values specified by the RMODE31 parameter 
have any effect on VSAM is on the setting just before an OPEN is issued. 
At other times, changing these values has no effect on the residency of the 
I/O related control blocks and I/O buffers. 

Note: The RMODE31 parameter is valid only when TYPE = LSR is 
specified. 

ALL 

both I/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside above 16 megabytes. 

BUFF 

specifics that only I/O buffers arc to reside above 16 megabytes. 

CB 

only the VSAM I/O related control blocks associated with the pool 
arc to reside above 16 megabytes. 

NONE 

both I/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside below 16 megabytes. This is the default. 

Note: In previous releases, the LOC = (BELOWJANY) parameter was 
used to specify that buffers in the pool be created above 16 megabytes. The 
RMODE31 parameter replaces the LOC parameter and the two parameters 
are mutually exclusive. If both are specified on the BLDVRP macro, the 
LOC parameter is ignored. 

SIIRPOOL * {0j number) 

specifics the identification number of a shared resource pool. Valid only 
when TYPE * LSR is also specified or defaulted. This parameter also 
requires that the RMODE31 parameter be specified. 

0 

specifies the shared pool with the ID of 0. It is the default LSR pool. 
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number 

specifies the shared pool with the ID of number where number can be 
0 to 15. The LSR control block and buffer pool residence is 
determined by the RMODE31 = keyword. 

MODE = {24|31} 

specifies the format of the BLDVRP parameter list that is to be generated. 
24 

specifies that a standard form (24-bit) parameter list address be 
generated. This is the default. 

31 

specifies that a long form (31-bit) parameter list address be generated, 
lliis value must be coded if the parameter list resides above 16 
megabytes. 

STRNO = number 

specifies the total number of placeholders required for all the data sets that 
are to share the resource pool. 1 is minimum; 255 is maximum. 

The number should equal the potential number of requests that may be 
issued concurrently for all the data sets that will share the resource pool If a 
request fails because the number of placeholders is insufficient (you receive a 
reason code of 64 (X'40') in the RPL feedback area), you may retry the 
request; it will be assigned a placeholder if one has been released. See 
Figure 8 on page 17 for a complete description of reason code 64 (X'40'). 

TYPE - I LSRlOATA ilNDEXl j GSR) 

specifics whether a local (LSR) or a global (GSR) resource pool is to be 
built. 

LSR 

specifies that the caller requests a local shared resource pool. A 
maximum of 16 data and 16 index resource pools can be built in one 
address space. Each resource pool must be built individually. 

DATA 

specifics that the caller wants to build a data resource pool. This 
option requires that LSR be specified. 'Hiis resource pool must exist 
before an index pool with the same shared pool ID can be built. 

INDEX 

specifies that the caller wants to build an index resource pool. This 
option requires that LSR be specified or defaulted. INDEX must be 
specified in order to create a separate index resource pool. If it is not 
specified, both data and index components will use the data pools. A 
data pool must already exist before an index pool with the same 
shared pool ID can be built. 

GSR 

specifies that the caller requests a global shared resource pool. 
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Only one BLDVRP TYPE = GSR may be issued for the system for each of 
the protection keys 0 through 7. The program that issues BLDVRP 
TYPE = GSR must be in supervisor state with protection key 0 to 7. 


| Example 1. Obtaining an LSR Pool above 16 Megabytes 


| This example shows how both a local shared resource pool and a BLDVRP 

| parameter list residing above 16 megabytes arc obtained. 

P00L1 BLDVRP BUFFERS=(1024(5)), 

STRN0=4, 

TYPE=LSR, 

MODE=31, 

RM0DE31=ALL 


The BLDVRP parameters are: 


• BUFFERS specifies that there is one buffer pool in the resource pool. This 
buffer pool contains 5 buffers, and each of these buffers is 1024 bytes. 

• STRNO specifics that 4 placeholders arc required for the data sets to share 
the resource pool. 

• TYPE specifics that a local resource pool is to be built. 


• MODE specifies that a parameter list is to be generated that may reside 
above or below 16 megabytes. The value of 31 must be coded if the 
parameter list resides above 16 megabytes. 

• RMODE31 specifies the location in storage for the I/O buffers and I/O 
related control blocks of the LSR pool. 


To connect the LSR pool to the data set, you must code the LSR and 
S11RPOOL parameters on the ACB. See “ACB Macro (Generate an Access 
Method Control Bloc!: at Assembly Time)” on page 34. 
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| Example 2. Request for Separate Data and Index Resource Pools 


j This example shows how the two separate data and index resource pools with an 

| identification equal to 3 are created. 


P00L1 BLDVRP BUFFERS=(2048(4)), 
TYPE=(LSR,DATA), 
SHRP00L=3, 

STRN0=2, 

RM0DE31=ALL 

* 

LTR R15,R15 

BNZ ERROR 


* 

P00L2 BLDVRP BUFFERS=(1024(5)), 
TYPE=(LSR,INDEX), 
SHRP00L=3, 

STRN0=2, 

RM0DE31=ALL 


Check return code. 

Do not build index if 
error. 


| Note: POOL1 must be created first because the data pool must exist before the 

| index pool with the same shared pool ID can be built. Also, only one data and 

| one index pool can be built for a shared pool ID. 
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CHECK Macro (Wait for Completion of Request) 


The format of the CHECK macro is: 



where: 

label 

is 1 to 8 characters that provide a symbolic address for the CHECK macro. 
RPL = address 

specifies the address of the request parameter list that defines the request. 

You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Example 1: Check Return Codes after an Asynchronous Request 

In this example, return codes arc checked after an asynchronous request. The 
CHECK macro is used to cause an exit to be taken if there is a logical or 
physical error or if the end of the data set is reached. 

REQPARMS RPL OPTCD=ASY 

GET RPL=REQPARMS 

LTR 15,15 Was the request completed 

successfully? 

BNZ REJECTED Zero indicates the request was 

accepted. If it was not 
accepted, register 15 contains 
Az REQPARtlS is active for 
another request. Continue to 
work on something that is not 
dependent on the request. 

CHECK RPL=REQPARMS CHECK would cause one of the 

three exits to be taken if 
there was a logical or physical 
error or if the end of the 
data set was reached and an 
active exit list exists. 

LTR 15,15 Test return indication is 

register 15. 

BNZ FAILURE Zero indicates the request 

completed successfully. If 
it failed, register 15 
contains 8 or 12: there was 
a logical or a physical 
error. 


REJECTED ... 
FAILURE ... 
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Unless you provide exit routines that terminate processing, always test register 15 
after the CHECK. If a routine returns to VSAM, register 15 is reset and control 
is passed back to your program immediately after the CHECK. An error analysis 
routine normally issues SHOWCB or TESTCB to examine the feedback field in 
the request parameter list, so that, when your processing program gets control 
back, it doesn't have to analyze the errors—but it may'alter its processing if there 
was an error. If you don't provide an error analysis routine, your program can 
issue SIIOVVCB or TESTCB to analyze an error when it gets control back 
following the CHECK. 

Example 2: Check Return Codes after a Synchronous Request 

With synchronous processing, you should test register 15 after the request 
because the request may not have been accepted (register 15 contains 4) or 
because an error might have occurred (8 or 12): 

GET RPL=REQPARMS 

LTR 15,15 Was the request completed 

successfully? 

BNZ REJFAIL If branch is not taken, was 

the request accepted and 
. completed succesfully? 

REJFAIL !.. 

Example 3: Overlap Processing 

In this example, the CHECK macro is used to wait for completion of a request 
before continuing to other processing. Access is asynchronous. 

BLOCK ACB 

LIST RPL ACB=BLOCK, Asynchronous access. 

AREA=WORK, 

AREALEN=50, 

OPTCD=ASY 

LOOP GET RPL=LIST 

LTR 15,15 

BNZ NOTACCEP 

Do other processing. 

CHECK RPL=LIST Suspends your processing to wait 

for completion of GET if 
necessary and to cause VSAM to 
indicate return codes. 

LTR 15,15 

BNZ ERROR 

Process the record. 

B LOOP 
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NOTACCEP ... Request was not accepted. 

ERROR ... Request failed. 


WORK DS CL50 Work area. 

After issuing the request, make sure that VSAM accepted it before you go on to 
other processing. When you have done as much other processing as you can, 
issue the Cl IECK macro. VSAM will not give you back control until the 
request is complete. If you don't want to issue CHECK until you know the 
request is complete, use the ECB parameter of the RPL macro or the 
lO = COMPLETE parameter of the TESTCB macro. After you issue the 
CHECK, VSAM immediately returns a code and takes an exit, if necessary. See 
“RPL Macro (Generate a Request Parameter List at Assembly Time)” on 
page 126 and “GENCB Macro (Generate a Request Parameter List at Execution 
Time)” on page 80 for information on the ECB parameter. 

Example 4: Suspend a Request for Many Records 

In this example, a CHECK macro is issued for the first request parameter list in a 
chain of parameter lists. If an error occurred for one of the request parameter 


lists in the chain and you have supplied error analysis routines, VSAM takes a 
LERAD or SYNAD exit before it returns control to your program after the 
CHECK. 

FIRST 

RPL 

ACB=BLOCK, 

AREA=AREA1, 

AREALEN=50, 

NXTRPL=SECOND 

OPTCD=ASY 

> 

SECOND 

RPL 

ACB=BLOCK, 

AREA=AREA2, 

AREALEN=50, 

NXTRPL=THIRIL> 

0PTCD=ASY 


THIRD 

RPL 

ACB=BL0CK, 

AREA=AREA3, 

AREALEN=50, 

0PTCD=ASY 

Last list does not indicate 
a next list. 

LOOP 

GET 

LTR 

RPL=FIRST 

15,15 

Request gives the address of 
the first request parameter 
list. 


BNZ 

NOTACCEP 


Do other processing. 



CHECK 

RPL=FIRST 



LTR 

15,15 



BNZ 

ERROR 
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Process the three records retrieved by the GET. 


B LOOP 
NOTACCEP ... 

ERROR 


AREA1 

DS 

CL50 

AREA2 • 

DS 

CL50 

AREA3 

DS 

CL50 


Request wasn't accepted. 

Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find 
out which one had an error. 

A single GET request causes VSAM 
to put a record in each of AREA1, 
AREA1, and AREA3. 


After the CHECK, register 15 is set to indicate the status of the request. A code 
of 0 indicates that no error was associated with any of the request parameter lists. 
Any other code indicates that an error occurred for one of the request parameter 
lists. You should issue a SIIOWCB macro for each request parameter list in the 
chain to find out which one had an error. VSAM doesn't process any of the 
request parameter lists beyond the one with an error. 
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CLOSE Macro (Disconnect Program and Data) 

The format of the CLOSE macro is: 


I label] 

CLOSE 

(address\,(options)],...) 



|,MODE={24|31)| 



|,TYPE -= T| 


where: 

label 

is 1 to 8 characters that provide a symbolic address for the CLOSE macro. 
address 

specifies the address of the access method control block or DCB for each 
data set to be closed. You may specify the address in register notation 
(using a register from 2 through 12—in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. If 
you specify only one address with a register, you must enclose the 
expression identifying the register in two sets of parentheses: for example, 
CLOSE ((2)). 

options 

are options parameters for use only in closing non-VSAM data sets. If any 
options arc specified with the address of an access method control block, 
VSAM ignores them. 

Note: Because the CLOSE parameters arc positional, include a comma for 
options (even if you don't specify options) before a subsequent parameter. 

MODE={24|31) 

specifics the format of the CLOSE parameter list that is to be built. 

24 

specifies that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 16 megabytes and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytes. This is the default parameter list 
format. 

31 

specifies that a long form (31-bit) parameter list address be built. 

This list can reside above or below 16 megabytes. This value must be 
coded if the parameter list resides above 16 megabytes or contains the 
address of an VSAM/VTAM ACB residing above 16 megabytes. 


TYPE = T 

specifics that VSAM is to complete outstanding I/O operations and update 
the catalog, but not disconnect the program from the data. 

You can issue a temporary CLOSE macro to cause VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
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information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. A 
temporary CLOSE doesn't disconnect the program from the data set, so 
your program can continue to process the data set without issuing an 
OPEN macro again. 

You must close and reopen a newly created VSAM data set before you can 
issue noncreate requests. A temporary close is not adequate for this 
purpose. 

Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE = T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close. 

| Example: CLOSE Macro 


L 


This example shows 
above 16 megabytes. 

how to close an ACB with a parameter list that may reside 

BLOCK! ACB 

*,RM0DE31=ALL 

VSAM control blocks 
and I/O buffers may 
be above 16 megabytes 

OPEN 

BL0CK1, 

M0DE=31 

OPEN/CLOSE parameter 
list may reside above 
16 megabytes 

CLOSE 

BLOCK1, 

M0DE=31, 

TYPE=T 



The CLOSE parameters are: 


• MODE = 31 is required if the OPEN/CLOSE parameter list resides above 16 
megabytes or if the ACB resides above 16 megabytes. 

• TYPE indicates a temporary CLOSE. This causes VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. 
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CNVTAD Macro (Convert Address) 

The format of the CNVTAD macro is: 

| label\ [CNVTAD | RPL = address ~~ 

RPL = address 

specifics the address of the request parameter list (RPL). The RPL 
identifies your opened VSAM data set and your arguments. The following 
RPL parameters and subparameters have meaning for the CNVTAD 
macro: 

ACB = address 

identifies your VSAM data set. 

ARG = address 

identifies your arguments. ITie address points to a parameter list, 
aligned on a fullword boundary as follows: 


Kcy-scqucnccd data set 


OfTsct 

Length 

Contents 

0 

3 

Reserved; unused 

3 

1 

Number of arguments (N) 

(N = 1 to 255) 

4+ (N-l)(10+ K) 

4 

Feedback RBA 
(K = key length) 

8 + (N-l)(10+ K) 

4 

Feedback volume serial number 
(K = key length) 

14+ (N-l)(10+ K) 

K 

Full key argument 
(K = key length) 

Entry-sequenced data set or relative record data set 

OfTsct 

Length 

Contents 

0 

3 

Reserved; unused 

3 

1 

Number of arguments (N) 

4 + (N-l)(4) 

4 

Feedback RBA 

8 + (N-l)(14) 

6 

Feedback volume serial number 

18 + (N-1)(14) 

6 

RBA/RRN argument 


The value for K is always 4 in an entry-sequenced or relative record 
data set. Therefore, 10 + K is always 14 for these two types of data 
sets. The maximum number of arguments allowed is 255. 
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ECB = address 

specifies the address of an event control block (ECB) which you may 
specify. VS AM indicates in the ECB whether or not a request is 
complete. This parameter is optional. 

OPTCD * ({ADR|KEY) 

,{ASY|SYN) 

,{KEQ|KGE) 

,FKS) 

ADR is only valid for entry-sequenced data sets. 

KEY is only valid for key-sequenced data sets and relative record dat 
a sets. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 

GEN is not supported; if specified, it will give an error indication. 

All other QPTGD subparameters are not applicable, and, if specified, 
arc ignored with no error indications. 

For a given list of discrete arguments, CNVTAD returns the volume serial 
number (volser) and the RBA corresponding to each argument in the parameter 
list feedback area. The data portion of your VSAM data set is not referenced and 
need not be mounted even if the sequence set is embedded. 

For an entry-sequenced data set, the volser is returned, and the same RBA 
specified in the argument field is also returned. 

Note: The RBA returned by CNVTAD in the case of a key-sequenced data set 
is not the exact RBA of the record. It is, in fact, an approximate value. (For 
data sets with the IMBED option, it is the RBA of the beginning of the sequence 
set for the record's control area; for data sets with NOIMBED, it is the RBA of 
the record's control interval.) When passed to MNTACQ, these RBA values 
cause MNTACQ to stage the appropriate cylinders corresponding to the 
requested arguments originally passed to CNVTAD. You should therefore use 
caution if you arc planning to use the RBAs obtained from CNVTAD for any 
purpose other than as input to MNTACQ. 

At the conclusion of this macro, the RPL is disconnected. Any positioning in 
effect prior to execution of this macro will be lost. You may have to reposition. 
Chained RPLs are not supported by CNVTAD. 
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DLVRP Macro (Delete VSAM Resource Pool) 

The DLVRP macro has a standard form and an execute form. The standard 
form builds a parameter list and passes control to VSAM to delete the resource 
pool. The execute form is described in Appendix B, “List, Execute, and 
Generate Forms of Macros” on page 171. 

The format of the DLVRP macro is: 


DLVRP 


TYPE = {LSR |GSR} 

|,MODE® 124.131)1 
|,SHRPOOL = {0\number}\ 


TYPE= fLSRIGSR) 

specifies the type of resource pool to be deleted: local (LSR) or global 
(GSR). When deleting an LSR pool, the number specified on the 
SIIRPOOL parameter indicates which LSR pool is to be deleted. If both a 
data resource pool and an index resource pool have the same SIIRPOOL 
number, both will be deleted. The program that issues DLVRP 
TYPE = GSR must be in supervisor state with protection key 0 to 7. 

MODE ={24|31) 

specifies the format of the DLVRP parameter list that is to be generated. 

24 

specifies that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 16 megabytes and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytes. This is the default parameter list 
format. 

31 

specifics that a long form (31-bit) parameter list address be built. 

This list can reside above or below 16 megabytes. This parameter 
value must be coded if the parameter list resides above 16 megabytes 
or contains the address of a VSAM/VTAM ACB residing above 16 
megabytes. 

SHRPOOL= {0| number) 

specifies the identification number of the shared resource pool that is to be 
deleted. Valid only when TYPE = LSR is also specified. The DLVRP 
parameter list may reside above or below 16 megabytes. 

0 

specifics the shared pool with the identification of 0. This is the 
default LSR pool identification number. 

number 

specifies the shared pool with the identification of number where 
number is a number from 0 to 15. 
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| Example: DLVRP Macro 

| This example shows how an LSR pool with a parameter list that may reside 

| above 16 megabytes and identification number other than 0 is deleted. 

DELPOOL DLVRP TYPE=LSR, 

I M0DE=31, 

SHRP00L=1 


The DLVRP parameters are: 

• TYPE specifies that an LSR pool is to be deleted. 

• MODE = 31 specifies the parameter list may reside above or below 16 
megabytes. 

• SIIRPOOL specifies that the data resource pool and the index resource po< 
(if any) with the idcntication number of 1 are to be deleted. 
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ENDREQ Macro (Terminate a Request) 

The format of the ENDREQ macro is: 


| label\ 


ENDREQ 


RPL = address 


where: 

label 

is 1 to 8 characters that provide a symbolic address for the ENDREQ 
macro. 

RPL = address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: The ENDREQ macro must not be issued when records are being loaded 
into a VSAM data set (load mode). ENDREQs issued while in load mode are 
ignored. 

Example: Release Positioning for Another Request 

In this example, the ENDREQ macro is used to cause VSAM to release 
exclusive control of a control interval containing a record. There are two request 
parameter lists, both of which require VSAM to have the ability to remember its 
position until VSAM is explicitly requested to forget its position. 


BLOCK 

ACB 

MACRF=(SEQ, 

DIR),STRN0=2 


3EQ 

RPL 

ACB=BLOCK, 

OPTCD=SEQ 

VSAM must remember its 
position. 

DIRUPD 

RPL 

ACB=BLOCK, 

OPTCD=(DIR,UPD) 

VSAM must remember its 
position and maintain 
exclusive control until 
explicitly requested to 
forget it by PUT or 
ENDREQ. 

LOOP 

GET 

RPL=SEQ 

VSAM now remembers its 
position for this request 


LTR 

BNZ 

15,15 

ERROR 

only while it is 
processing the request. 


GET 

RPL=DIRUPD 

VSAM can remember its 
position for this request 


LTR 

15,15 

The control interval will 
be placed in exclusive 


BNZ 

ERROR 

control until either 
ENDREQ or PUT UPD is 
issued. 
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ENDREQ 


Decide whether to update the record. 



B 

PUT 

LTR 

FORGET 

RPL=DIRUPD 

15,15 

No; do not update the 
record. 

Yes; update the record, 
causing VSAM to forget its 
position for DIRUP. 


BNZ 

ERROR 



B 

LOOP 


FORGET 

ENDREQ RPIfDIRUPD 

LTR 15,15 

Cause VSAM to forget its 
position for DIRUPD. 
Release exclusive control. 


BNZ 

ERROR 



B 

LOOP 


ERROR 

XXX 


Request wasn't accepted or 


failed. 


The use of ENDREQ illustrated here causes VSAM to release exclusive control 
of the control interval for a record. When PUT is issued after a DIRUPD GET 
request, ENDREQ need not be issued, because PUT causes VSAM to release 
exclusive control (the next DIRUPD GET doesn't depend on VSAM's 
remembering its position). Another result of ENDREQ is that current buffers 
arc written if they have been modified. 

To cause VSAM to give up its position associated with a chain of request 
parameter lists, specify the first request parameter list in the chain in your 
ENDREQ macro. 

ENDREQ can also be used to cancel an asynchronous request, rather than 
suspending processing with CHECK. 

Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE = T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close, in is adequate. 

Because VSAM remembers its position after a direct GET with OPTCD = UPD 
or LOC, if no PUT or ENDREQ follows, you can switch to sequential access 
and use the positioning for a GET. 
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ERASE Macro (Delete a Record) 

The format of the ERASE macro is: 

[labelj ERASE RPL = address 

where: 

label 

is 1 to 8 characters that provide a symbolic address for the ERASE macro. 
RPL ** address 

specifics the address of a request parameter list that defines the request. 

You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-typc address constant. 

With ERASE processing of key-sequenced data sets, VSAM attempts to make 
the control interval available to the control area when the last record in the 
control interval is erased, 'thus, kcy-scqucnccd data set control intervals can be 
reused for new records whose keys fall anywhere within the control area's range 
of keys. You may suppress the process of reclaiming the control interval by 
setting RPLNOCIR in the RPL used for ERASE. The high key control interval 
of a control area is never reclaimed. 

Example 1: Keyed-Direct Deletion 

In this example, GE T and ERASE macros are used to retrieve and delete records. 
Not every record retrieved for deletion is deleted. ITic search argument is a full 
key (5 bytes), compared equal. 

DELETE ACB MACRF=(KEY,DIR, 

OUT) 

LIST RPL ACB=DELETE, 

AREA=W0RK, 

AREALEN=50, 

ARG=KEYFIELD, 

OPTCD=(KEY,DIR, 

SYN,UPD, UPD indicates deletion. 

MVE,FKS, 

KEQ) 


LOOP MVC KEYFIELD,source Search argument for 

retrieval, from a table 
or transaction record. 

GET RPL=LIST 
LTR 15,15 
BNZ ERROR 
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Decide whether to delete the record. 


BE 

LOOP 

No; retrieve the next record. 

ERASE 

RPL=LIST 

Yes; delete the record. 

LTR 

15,15 


BNZ 

ERROR 


B 

LOOP 



ERROR ... Request was not accepted, or 

failed. 

WORK DS CL50 Examine the data record here. 

KEYFIELD DS CL5 Search argument. 

When you retrieve a record for deletion (OPTCD= UPD, same as retrieval for 
update), VSAM is positioned at the record retrieved, in anticipation of a 
succeeding ERASE (or PUT) request for that record. You are not required to 
issue such a request, though. Another GET request nullifies any previous 
positioning for deletion or update. 

Keyed-sequential retrieval for deletion varies from direct in not using a search 
argument (except for possible use of the POINT macro). Skip-sequential 
retrieval for deletion (OPTCD = (SKP,UPD)) has the same effect as direct, but it 
is faster or slower depending on the number of control intervals separating the 
records being retrieved. 

Example 2: Addrcsscd-Scqucntial Deletion 

In this example, the ERASE macro is used to delete records from a 
kcy-scqucnced data set. Not every record retrieved for deletion is deleted. 

Skipping is effected by the POINT macro. 

DELETE ACB MACRF=(ADR,SEQ, 

OUT) 

REQUEST RPL ACB=DELETE, 

AREA=WORK, 

AREALEN=100, 

ARG=ADDR, 

OPTCD=(ADR,SEQ, 

ASY, 

UPD,MVE) UPD indicates deletion. 

LOOP ... Decide whether you need to 

skip to another position 
forward or backward). 

B RETRIEVE No; bypass the POINT. 

MVC ADDR,source Yes; move search argument 

for POINT into 
search-argument field. 
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POINT 

RPL=REQUEST 

Position VSAM to the 
record to be retrieved 
next. 


LTR 

15,15 



BNZ 

ERROR 



CHECK 

RPL=REQUEST 



LTR 

15,15 



BNZ 

ERROR 


RETRIEVE 

GET 

RPL=REQUEST 



LTR 

15,15 



BNZ 

ERROR 



CHECK 

RPL=REQUEST 



LTR 

15,15 



BNZ 

ERROR 


Decide whether to delete the record. 



BE 

LOOP 

No; skip ERASE and CHECK. 


ERASE 

RPL=REQUEST 

Yes; delete the record. 


LTR 

15,15 



BNZ ' 

ERROR 



CHECK 

RPL=REQUEST 



LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


ERROR 



Request was not accepted 


. 


or failed. 

ADDR 

DS 

F 

RBA search argument for 
POINT. 

WORK 

DS 

CL100 

Work area. 


Addressed deletion is allowed only for a kcy-sequcnccd data set. The records of 
an entry-sequenced data set are fixed. When records are deleted using addressed 
deletion from a kcy-scquenccd data set, the index is not updated. 
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EXLST Macro (Generate an Exit List at Assembly Time) 


The format of the EXLST macro is: 


\label[ 

EXLST 

IAM-VSAMI 

|,EODAD = (address\,A | N||,L J)| 

I,IOPID = (address)] 
f JRNAD = (address\,A | N)(,L|)| 



(,LERAD - (acWlrewf ,A |N||,L|)| 

|,SYNAD = (address\ f A | N||,L|)| 

|,LPAD = (a<MrwJ,A|Nl[,L|)| 


Values for EXLST macro subparameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

label 

is 1 to 8 characters that provide a symbolic address for the exit list that is 
established. 

AM = VS AM 

specifics that the access method using the control block is VSAM. 

EODAD = {address\,A^ N ||,L|) 

IOPID = (address) 

JRNAD = {address\,N\ M ||,L|) 

LERAD = (address\,A\ N|f ,L|) 

SYNAD = (aJ</re*r[,A|N||,L|) 

UPAD - (address[,A\ N|(, A j) 

specify that you are supplying a routine for the exit specified. 

For more information about user exit routines, see Data Facility Product: 
Customization. 

The exits and values that can be specified for these routines arc: 

EODAD 

specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 

lOPID 

specifies that an I/O prevention identifier is provided to terminate I/O 
and prevent new I/O from being started for the data sets associated 
with the identifier. When the IOPID address is specified, the 
identifier is always assumed to be active. 
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JRNAD 

specifies that an exit is provided for journalizing transactions as you 
process data records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 

SYNAD 

specifics that an exit is provided for analyzing physical errors. 

UPAD 

specifies that an exit is provided for user processing during a VS AM 
request. The GENCB, MODCB, SIIOWCB, and TESTCB macros 
do not support the UPAD user exit routine. 

address 

is the address of a user-supplied exit routine or an I/O prevention 
identifier. The address must immediately follow the equal sign. 


A|N 

specifics that the exit routine is active (A) or not active (N). VSAM 
docs not enter a routine whose exit is marked not active. 

L 

specifics that the address is that of an 8-bytc field that contains the 
name of an exit routine in a partitioned data set that is identified by a 
JOBLIB or STEP LIB DD statement or in SYS1.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 


Example: EXLST Macro 


In this example, an EX LSI' macro is used to identify exit routines that are 
provided for analyzing logical and physical errors. The label, EXITS, of the 
EXLST macro is used in an ACB or GENCB macro that generates an access 
method control block to associate the exit list with an access method control 
block. The exit list generated by this example is built when the program is 
assembled. 

EXITS EXLST EODAD=(ENDUP,N), EXITS gives symbolic 

LERAD==LOGICAL, address of the exit list. 
SYNAD=(ROUTNAME,L) 

ENDUP EODAD routine. 


LOGICAL 

ROUTNAME DC C*PHYSICAL' 


LERAD routine. 

Pad shorter names with 
blanks: C'SYN'or CL8'SYN'. 


The EXLST macro's parameters are: 

• EODAD specifies that the end-of-data routine is located at ENDUP and is 
not active. 
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• LERAD specifies that the logical error routine is located at LOGICAL and 
active. 

• SYNAD specifies that the physical error routine's name is located at 
ROUTNAME. 


68 MVS/XA VSAM Administration: Macro Instruction Reference 



GENCB-ACB 


I GENCB Macro (Generate an Access Method Control Block at 
l Execution Time) 


The format of the GENCB macro used to generate an access method control 
block is: 


1 


\label\ 


GENCB 


BLK = ACB 
I.AM = VSAMI 
(,BSTRNO = number] 

IjBUFNI) = number] 
jjBbFNI = number] 

\,BUFSV = number] 
|,CATALOG=YES|NOJ 
|,COPIES = number] 

(,CRA = SCRAjUCRAI 
IjDDNAME* ddname] 

|,EXLST= address] 

I,LENGTH = number] 

|,LOC = BELOW | AN Y| 

|,M ACRE = (|ADR||,CNV||,KEY) 
LCFX1NFXI 
l. DDN IDSNI 
LDFRI NDFI 
I,DIRH,SE(2||,SKP| 

I,ICI|NCI1 

|,IN||,OUT| 

LNLS1SIS1 
F NRM IA1X1 
I.NRSIRST1 
LNSRILSRIGSR1 
|,Nl)BiUBF|)I 
j,MAREA^ address] 
j,MLEN = number] 

|,PASS\\T) = address] 

|,RMODE31 = (ALLlBUFFICBI NONE) l 
|,SHRPOOL= {0\number}\ 

|,STRNO = number] 
j,WAREA = address\ 


| Note: The RMODE parameter replaces the AMODE31 subparameter used in 

| previous releases. 

The subparameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
| constants, and as indirect S-type address constants. Appendix C, “Operand 

| Notation” on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the GENCB macro. 
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BLK - ACB 

specifies that you are generating an access method control block. 

AM- VSAM 

specifies that the access method using this control block is VSAM. 

BSTRNO — number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the 
object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can also influence 
performance. The VSAM control blocks for the set of strings specified by 
BSTRNO are allocated on contiguous virtual storage, whereas this is not 
guaranteed for the strings allocated by dynamic extension. 

BUFND = number 

specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at least 2, because the default for STRNO is l). 'Hie number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. Tfie default is the minimum number required. A larger number 
for BUFND can improve the performance of sequential access. 


BUFXI = number 

specifies the number of I/O buffers VSAM is to use for transmitting index 
entries between virtual and auxiliary storage for keyed access. A buffer is 
the size of a control interval in the index. 'Hie minimum number is the 
number specified for STRNO (if you omit STRNO, BUFNI must be at 
least 1, because the default for STRNO is 1). You can supply the number 
by way of the JCL DD AMP parameter as well as by way of the macro. 
The default is the minimum number required. A larger number for BUFNI 
can improve the performance of keyed-direct retrieval. 

BUFSP =* number 

specifies the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFFRSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• The amount specified in the catalog (BUFFERSPACE), 

• The amount determined from BUFND and BUFNI, or 
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• The minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount is smaller than the minimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not less than the minimum number, Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not less than 1 more than the minimum number. Then, 
if required, the number of data buffers is decreased to not less than the 
minimum number. If still required, 1 more is subtracted from the 
number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to less than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. 

CATALOG - YES1NO 

specifics whether a catalog is being opened as a catalog (YFS) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, etc.). To open a 
password-protected catalog for processing with VSAM macros, you must 
supply its master password. When CATALOG = YFS is coded, the catalog 
must be processed with an SVC designed for that purpose. (Access method 
services, for example, processes catalogs with SVC 26.) The request macros 
are invalid for processing a catalog “as a catalog.” VSAM users should alter 
the contents of a catalog only by access method services commands. 

-COPIES *= number 

specifies the number of copies of the access method control block VSAM is 
to generate. All the copies are identical. You can use MODCB to tailor 
each one for the data set and processing you want for it. MODCB is 
described later in this chapter. 
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CRA = SCRAJUCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME = ddname 

is 1 to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the MODCB macro before opening 
the data set. MODCB is described later in this chapter. 

EXLST = address 

specifics the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1. Omitting this parameter indicates that you have no 
exit routines. Exit routines are described in the chapter “User-Written Exit 
Routines” in Data Facility Product: Customization. 

LENGTH — number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the access method control block(s). (See the WAREA 
parameter.) When the LENGTH value is specified, it cannot exceed 65535 
(X' FFFF 1 ). 

LOC = BELOW ! ANY 

BELOW 

specifies that VSAM is to construct an ACB in an area of virtual 
storage below 16 megabytes at execution time. This is the default. 


specifies that VSAM is to construct an ACB in an area of virtual 
storage above 16 megabytes, if possible, at execution time. 

MACRF = (|ADR|I,CNV||,KEYJ 
LCFX1 NFX1 
I. DDN IDSNI 
LDFR1NPFI 
1.D1RH. SEOH .SKPI 
|,ICI|NCI1 
I,INII,OUT| 

IMSISISI 

L NRM 1AIX1 

LNRS1RSTI 

LNSR1LSR1GSR1 

LNUBIUBFD 

specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
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data set. You must specify all the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
The subparameters are shown in Figure 12 on page 38. They are arranged 
in groups, and each group has a default value (indicated by underlining). 
You may specify subparameters in any order. You may specify both ADR 
and KEY to process a key-sequenced data set. You may specify both DIR 
and SEQ; with keyed access, you may specify SKP as well. If you specify 
OUT and want merely to retrieve some records as well as update, delete, or 
insert others, you need not also specify IN. 

Note: The RMODE31 parameter replaces the AMODE31 subparameter 
used in previous releases. 

MAREA = address 

specifics the address of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. 

MLEN = number 

specifics the length of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. 

PASSWD = address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the field contains the length (in binary) of the password 
(maximum of 8 bytes). Zero indicates that no password is supplied. If the 
data set is password protected and you don't supply a required password in 
the access method control block, VSAM may give the console operator the 
opportunity to supply it when you open the data set. 

RMODE3I = IALLIBUFF1CB1 NONEI 

specifies where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 

The values specified by the RMODE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
changing these values has no effect on the residency of the control blocks 
and I/O buffers. 

The virtual storage location of the ACB is independent of the RMODE31 
parameter. An ACB may reside cither above or below 16 megabytes. 

ALL 

both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 

only VSAM I/O buffers are to be obtained above 16 megabytes. 

CB 

only VSAM control blocks are to be obtained above 16 megabytes. 
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NONE 

both VSAM control blocks and I/O buffers are to be obtained below 
16 megabytes. This is the default. 

SHRPOOL-{/iwm6er|0) 

specifics the identification number of the resource pool to be used for LSR 
processing. The default is SHRPOOL=0. 

STRNO = number 

specifies the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. A request is defined by a given request 
parameter list or chain of request parameter lists. See “RPL Macro 
(Generate a Request Parameter List at Assembly Time)” on page 126 and 
“GENCB Macro (Generate a Request Parameter List at Execution Time)” 
on page 80 for information on request parameter lists. 

VVAREA = address 

specifics the address of an area in which to generate the access method 
control block(s). 

The area must begin oh a fullword boundary. 

This parameter is paired with the LENGTH parameter. You must supply 
the LENGTH parameter if you specify an area address. 

Note: If you do not specify an area in which the access method control 
block is to be generated, VSAM obtains virtual storage space for the area 
(as specified by the LOC = keyword). VSAM returns the address of the 
area containing the control btock(s) in register 1 and the length of the area 
in register 0. You can find out the length of each control block by dividing 
the length of the area by the number of copies, llie address of each control 
block can then be calculated by this offset from the address in register 1. 
You can find the length of an access method control block with the 
SHOWCB macro. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (VVAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 
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Example: GENCB Macro (Generate an Access Method Control Block) 


In this example, a GENCB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. This example specifics that 
the space for the control block be obtained above 16 megabytes. The access 
method control block generated by this example is built when the program is 
executed. 


GENCB 


GENCB BLK=ACB,AM=VSAM, 
BUFND=4,BUFNI=3, 
BUFSP 3S 19456, 
DDNAME=DATASETS, 
EXLST=EXITS, 
LOC=ANY, 
MACRF=(KEY,DIR, 
SEQ,OUT), 
PASSWD=FIELD, 
RM0DE31=ALL, 
STRN0=2 


One copy generated; VSAM 
gets the storage for it, 
because the WAREA LENGTH 
parameters have been 
omitted. 


ST 1,ACBADDR Save the address of the 

access method control 
block. 


ACBADDR DS 


FIELD DC 


F The address of the 

access method control 
block is saved in 
ACBADDR. 

FL1 1 6 ’, C 1 CHANGE * CHANGE, the password, has 
6 characters. 


TTie GENCB macro's parameters are: 

• BUFND specifics four I/O buffers for data; BUFNI specifics three I/O 
buffers for index entries; and BUESP specifics 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and of index entries that arc 1024 bytes. 

• DDNAME specifies that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifics that the exit list associated with this access method control 
block is named EXI TS. 

• LOC specifics that VSAM obtain virtual storage for the ACB from an area 
that may be above 16 megabytes. 

• MACRF specifies keyed direct and keyed sequential processing for both 
insertion and update. 

• PASSVVD specifics the location, FIELD, of the password provided. 

4 

• RMODE31 specifics that VSAM obtain storage for the VSAM control 
blocks and I/O buffers in an area above 16 megabytes when the ACB is 
opened. 

• STRNO specifies that two requests will require concurrent positioning. 
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GENCB Macro (Generate an Exit List at Execution Time) 


The format of the GENCB macro used to generate an exit list is: 


| label\ 

GENCB 

BLK = EXLST 



LAM = VS AMI 

I,EODAD = (address], A | N|[,LJ)J 

LJRNAD = (a<fcfcr|,A|N||,L|)| 

|,LERAD = (acfc/reM|,A|N||,L|)| 

I,SYNAD - (address],X] N||,LJ)| 

1,COPIES =» number] 

I,LENGTH = number] 

I.LOC - BELOW! ANYI 
jjWAREA = address\ 


The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

label 

is 1 to 8 characters that provide a symbolic address for the GENCB macro. 

BLK = EXLST 

specifies that you are generating an exit list. 

AM- VS AM 

specifies that the access method using this control block is VS AM. 

|,EODAD - (address[,A | NJ|,L 1)1 
(jJRNAD = (address ], A| N|(,L|)| 

(,LERAD - , A |N|I,L|)| 

I.SYNAD = (address ], A | N ||,L|)| 

specify that you are supplying a routine for the exit named. 

For more information about user exit routines, see Data Facility Product: 
Customization. 

If none of these user exit routines is specified, VSAM generates an exit list 
with inactive entries for all the exits. The exits and values that can be 
specified for them are: 

EODAD 

specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 
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JRNAD 

specifies that an exit is provided for journaling as you process data 
records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 
SYNAD 

specifics that an exit is provided for analyzing physical errors. 
address 

is the address of a user-supplied exit routine. The address must 
immediately follow the equal sign. 


A|N 

specifies that the exit routine is active (A) or not active (N). VSAM 
does not enter a routine whose exit is marked not active. 

L 

specifics that the address is that of an 8-byte field that contains the 
name of an exit routine in a partitioned data set that is identified by a 
JOBLIB or STEPLIB DD statement or in SYS1.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 
L may precede or follow the A or N specification. 

COPIES = number 

specifies the number of copies of the exit list you want generated. GENCB 
generates as many copies as you specify (default is 1) when your program is 
executed. All copies are the same. You can use MODCB to change some 
or all of the addresses in a list. (MODCB is described later in this chapter.) 

LENGTH = number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the exit list(s). (See the WAREA parameter.) When 
the LENGTH value is specified, it cannot exceed 65535 (X' FFFF ’). 

LOC = BELOW j ANY 

BELOW 

specifics that VSAM is to construct an exit list in an area below 16 
megabytes at execution time. This is the default value. 


ANY 

specifics that VSAM is to construct an exit list in an area above 16 
megabytes, if possible, at execution time. 

WAREA = address 

specifies the address of an area in which the exit list(s) is to be generated. 
The area must begin on a fuilword boundary. 
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This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 

Note: If you did not specify an area in which the exit list is to be 
generated, VSAM obtains virtual storage space for the area (as specified by 
the LOC = keyword). VSAM returns the address of the area in which the 
exit lists(s) is to be generated in register 1, and the length of the area in 
register 0. You can find the length of each exit list by dividing the length of 
the area by the number of copies. The address of each exit list can then be 
calculated by this offset from the address in register 1. You can find the 
length of an exit list with the SHOVVCB macro, described under 
“SIIOVVCB Macro (Display Fields of an Exit List)” on page 139. 


If you arc generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH) for them enables you to address all of 
them with one base register and to avoid repetitive requests for virtual 
storage. 

Example: GENCB Macro (Generate an Exit List) 


In this example, a GENCB macto is used to generate an exit list when the 
program is executed. 


EXITS GENCB BLK=EXLST 


LTR 

BNZ 

ST 

EOD EQU 

LOGICAL EQU 
ERROR DC 

EXLSTADR DS 


EOBAD^C EOD, N)» 
LERAD=LOGICAL, 
SYNAD=(ERROR, 
A,L) 

15,15 

ERROR 

1,EXLSTADR 

* 

* 

C'PHYSICAL* 

F 


The GENCB macro's parameters arc: 


Address of the exit list is saved. 
EODAD routine. 

LERAD routine. 

Name of the SYNAD module. 

Save area for exit-list address. 


• BLK specifies that an exit list is to be generated. 


• EODAD specifics that the end-of-data routine is located at EOD and is not 
active. 


• LERAD specifies that the logical error routine is located at LOGICAL; 
because neither A nor N is specified, the LERAD routine is marked active by 
default. 

• SYNAD specifies that the physical error routine's name is located at 
ERROR. 
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Because no area was specified in which the exit list was to be. generated, VSAM 
obtained virtual storage for the exit list and returned the address in register 1. 
Immediately after the GENCB macro, the address of the exit list, contained in 
register 1, is moved to EXLSTADR. EXLSTADR may be specified in a 
GENCB macro that generates an access method control block or in a MODCB, 
SHOWCB, or TESTCB macro that modifies, displays, or tests fields in an exit 
list. 
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GENCB Macro (Generate a Request Parameter List at Execution 
Time) 


The format of the GENCB macro used to generate a request parameter list is: 


\label\ 


GENCB 


BLK = RPL 
[,ACB = address ) 

|,AM =* VSAMJ 
|,AREA =* address | 
j,AREALEN = number\ 

(,ARG = address\ 

(,COPIES = number\ 

1,ECB = address\ 

|,KEYLEN = number] 

I,LENGTH = number] 

(,LOC - BELOW 1 ANY! 
(jMSGAREA = address\ 
j,MSGLEN = number] 
|,NXTRPL = address] 

|,OP TCD « ([ADRICNYI KEYI 
LDIRISEQISKPI 
L ARP H-RPI 
|,FWD|BWD| 
LASYI SYN1 
LNSP1NUPIUPPI 
|,KE(2|KGE| 
I.FKSIGENI 
|,LOC|MVE|)| 
[jRECLEN = number] 

[,TR ANSID = number] 
f,WAREA = address\ 


The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181 further defines these operand expressions. 

The parameters of the GENCB macro to generate a request parameter list are 
optional in some cases, but required in others. It is not necessary to omit 
parameters that are not required for a request; they arc ignored. Thus, for 
example, if you switch from direct to sequential retrieval with a request parameter 
list, you don't have to zero out the address of the field containing the search 
argument (ARG = address). 

label 

is 1 to 8 characters that provide a symbolic address for the GENCB macro. 
For addressing lists generated by GENCB, see the discussion of the 
COPIES parameter. 
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BLK = RPL 

specifies that you are generating a request parameter list. 

ACB = address 

specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you omit this parameter, you 
must issue MODCB to specify the address of the access method control 
block before you issue a request. (MODCB is described later in this 
chapter.) 

AM- VSAM 

specifies that the access method using this control block is VSAM. 

AREA = address 

specifics the address of a work area to and from which VSAM moves a data 
record if you request it to do so (with the RPL parameter 
OPTCD= MVE). If you request that records be processed in the I/O 
buffer (OPTCD= LOC), VSAM puts into this work area the address of a 
data record within the I/O buffer. 

AREALEN = number 

specifics the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for OPTCD= MVE is the size of a 
data record (or the largest data record, for a data set with records of variable 
length). For OPTCD = LOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 

ARG = address 

specifics the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG field must be 4 bytes long. For direct or skip-sequential 
processing, this field contains your search argument, a relative record 
number. For sequential processing (OPTCD = (KEY,SEQ)), the 4 bytes 
arc required for VSAM return the feedback RRN. For keyed access 
(OPTCD= KEY), the search argument is a full or generic key; for 
addressed access (OPTCD = ADR), it is an RBA. If you specify a generic 
key (OPTCD = GEN), you must also specify in the KEYLEN parameter 
how many of the bytes of the full key you are using for the generic key. 

COPIES = number 

specifics the number of copies of the request parameter list you want 
generated. GENCB generates as many copies as you specify (default is 1) 
when your program is executed. 

The copies of a request parameter list can be used to: 

• Chain lists together to gain access to many records with one request 

• Define many requests to gain access to many parts of a data set 
concurrently 

All copies generated are identical; you must use MODCB to tailor them to 
specific requests. MODCB is described in this chapter. 
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ECB = address 

specifies the address of an event control block (ECB) that you may supply. 
VS AM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which are described in Data Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. This parameter is always optional. 

KEYLEN = number 

specifies the length, in bytes, of the generic key (OPTCD = GEN) you are 
using for a search argument (given in the field addressed by the ARG 
parameter). This parameter is required with a search argument that is a 
generic key. The number can be 1 through 255. For full-key searches, 
VSAM knows the key length, which is taken from the catalog definition of 
the data set when you open the data set. 

LENGTH = number 

specifies the length, in bytes, of the area, if any, that you arc supplying for 
VSAM to generate the request parameter list(s). (Sec the WAREA 
parameter.) When the LENGTH value is specified, it cannot exceed 65535 
(X'FFFF '). 

You can find out how long a request parameter list is with the SIIOWCB 
macro, described later in this chapter. 

LOC - BELOW 1 ANY 

BELOW 

specifics that storage for the RPL be obtained from virtual storage 
below 16 megabytes. This is the default value. 


ANY 

specifics that storage be obtained from virtual storage above 16 
megabytes if possible. 

MSGAREA = address 

specifies the address of an area that you are supplying for VSAM to send 
you a message in case of a physical error. (The format of a physical error 
message is given under “Physical Errors” in the chapter “Request 
Macros.”) 

MSGLEN = number 

specifics the size, in bytes, of the message area indicated in the MSGAREA 
parameter. The size of a message is 128 bytes; if you provide less than 128 
bytes, no message is returned to your program. This parameter is required 
when MSGAREA is coded. 
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NXTRPL = address 

specifies the address of the next request parameter list in a chain. Omit this 
parameter from the macro that generates the only or last list in the chain. 
When you issue a request that is defined by a chain of request parameter 
lists, indicate in the request macro the address of the first parameter list in 
the chain. A single request macro can be defined by multiple request 
parameter lists, such that a GET, for example, can cause VSAM to retrieve 
two or more records. 

OPTCD = (1ADRICNVI KEYI 
LPIRISFQISKP1 
I. ARD ILRD1 
I. FWD IBWDI 
I.ASYI SYNI 
|,NSP|NUP|UPD| 

|,KEQ|KGE1 

EFKSIGENl 

IXOCI MVEI ) 

specifies the subparameters that govern the request defined by the request 
parameter list. Each group of subparameters has a default; subparameters 
arc shown in Figure 13 on page 128 with defaults underlined. Only one 
subparameter Jfrom each group is effective for a request. Some requests do 
not require an subparameter from all of the groups to be specified. The 
groups that are not required are ignored; thus, you can use the same request 
parameter list for a combination of requests (GET, PUT, POINT, for 
example) without zeroing out the inapplicable subparameters each time you 
go from one request to another. 

RECLEN = number 

specifics the length, in bytes, of a data record being stored. If the records 
you are storing are all the same length, you will not need to change 
RECLEN after you set it. TTiis parameter is required for PUT requests. 

For GET requests, VSAM puts the length of the record retrieved in this 
field in the request parameter list. It will be there if you update and store 
the record. 

TRANSID « number 

specifics a number that relates modified buffers in a buffer pool. Use in 
shared resource applications and a description are in “Sharing Resources” 
in VSAM Administration Guide. 

WAREA *= address 

specifics the address of an area in which the request parameter list(s) is to 
be generated. 

The area must begin on a fullword boundary. 

This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 

Note: If you did not specify an area in which the request parameter list is 
to be generated, VSAM obtains virtual storage space for the area (as 
specified by the LOC = keyword). VSAM returns the address of the area in 
which the request parameter list(s) is generated in register 1, and the length 
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of the area in register 0. You can find the length of each list by dividing the 
length of the area by the number of copies. You can then calculate the 
address of each list by using the length of each list as an offset. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 

Building a Chain of Request Parameter Lists 

When GENCB is used to build a chain of request parameter lists, the request 
parameter lists may be chained using only GENCB macros or using GENCB and 
MODCB macros together. When only GENCB is used, the request parameter 
lists are created in reverse order, as follows: 

SECOND GENCB BLK=RPL 

LR 2,1 

FIRST GENCB BLK=RPL,NXTRPL=(2) 

SECOND GENCB creates the second request parameter list, which makes its 
address available for the first request parameter list. Ihe address of the request 
parameter list is returned in register 1 and is loaded into register 2. FIRST 
GENCB creates the first request parameter list and supplies the address of the 
next request parameter list using register notation. GENCB and MODCB 
macros may be used together to create a chain of request parameter lists, as 


follows: 

GENCB 

BLK=RPL,C0PIES=2 

LR 

2,0 

SRL 

2,1 

LR 

3,1 

LA 

4,0(2,3) 

MODCB 

RPL=(3),NXTRPL=(4) 


The GENCB macro creates two request parameter lists. The length of the 
parameter lists is returned in register 0 and loaded into register 2. The address of 
the area in which the lists were created (and, therefore, the address of the first 
one) is returned in register 1 and loaded into register 3. The SRL statement 
divides the total length of the area (register 2) by 2. The LA statement loads the 
address of the second request parameter list into register 4. The MODCB macro 
modifies the first request parameter list (register 3) by supplying the address of the 
second request parameter list (register 4) in the NXTRPL parameter. 

Each request parameter list in a chain should have the same OPTCD 
subparameters. Having different subparameters may cause logical errors. You 
can't chain request parameter lists for updating or deleting records—only for 
retrieving records or storing new records. You can't process records in the I/O 
buffer with chained request parameter lists. (OPTCD = UPD and LOC are 
invalid for chained request parameter lists.) 
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Example: GENCB iMacro (Generate a Request Parameter List) 

In this example, a GENCB macro is used to generate a request parameter list. 


ACCESS 

GENCB 

BLK=RPL, 

ACB=ACCESS, 

AM=VSAM, 

AREA=WORK, 

AREALEN=125, 

ARG=SEARCH, 

LOC=ANY, 

MSGAREA=MESSAGE 

MSGLEN=128, 


• 

OPTCD=(SKP,UPD) 

ACCESS 

ACB 

MACRF=(SKP,OUT) 

WORK 

DS 

CL125 

SEARCH 

DS 

CL8 

MESSAGE 

DS 

CL128 


The GENCB macro's parameters are: 

• BLK specifies that a request parameter list is to be generated. 

• ACB specifies that the request parameter list is associated with a data set and 
processing options identified by ACCESS. 

• AREA and AREALEN specify a 125-byte work area to be used for 
processing records. 

• ARG specifies the address of the search argument. 

• LOC specifics that VSAM obtain storage for the request parameter list in an 
area above 16 megabytes. 

• MSGAREA and MSGLEN specify a 128-byte area to be used for 
physical-error messages. 

• OPTCD specifies the subparameters that govern the request defined by the 
request parameter list identified by SKP and UPD. 
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GET Macro (Retrieve a Record) 

The format of the GET macro is: 


\label\ 


GET 


RPI = address 


where: 

label 

is 1 to 8 characters that provide a symbolic address for the GET macro. 
RPL = address 

specifics the address of the request parameter list that defines this GET 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 

Example I: Keyed-Sequential Retrieval (Forward) 

In this example, a GET macro is used to sequentially retrieve records by key. 
Retrieval is in a forward direction. Fixed-length, 100-byte records are moved to a 


work area. 

Processing,is synchronous. 


INPUT 

ACB 

MACRF=(KEY, 

All MACRF and OPTCD 



SEQ,IN) 

subparameters specified are 
defaults and could have 
been omitted. 

RETRVE 

RPL 

AC B=INPUT, 
AREA=IN, 

AREALEN=100, 
0PTCD=(KEY,SEQ, 



• 

SYN,NUP,MVE) 


LOOP 

GET 

RPL=RETRVE 

This GET or identical GETs can 
be issued, with no change in 




the request parameter list, to 
retrieve subsequent records in 
key sequence. 


LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


ERROR 

• • • 


Request was not accepted, or 


• 


failed. 

IN 

DS 

CL100 

IN contains a data record after 
GET is completed. 


The records are retrieved in key sequence in a forward direction. No search 
argument has to be specified; VSAM is positioned at the first record in key 
sequence when the data set is opened, and the next record is retrieved 
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automatically as each GET is issued. The branch to ERROR could also be 
taken if the end of the data set is reached. 

Example 2: Keyed-Sequential Retrieval (Backward) 

This example is the same as the previous one, except that a POINT macro 
instruction is issued to the last record in the data set and the records are retrieved 
in a backward direction. 


INPUT 

ACB 

DDNAME=INPUT, 

EXLST=EXLST1 


RETRVE 

RPL 

ACB=INPUT, 
AREA=IN, 
AREALEN=100, 
OPTCD=(KEY,SEQ, 
LRD,BWD) 

Define RPL for last record 
positioning and backward 
processing. 

EXIST1 

EXIST 

EODAD=EOD 

Define end of data. 


POINT 

LTR 

RPL=RETRVE 

15,15 

Position to last record (no 
argument is required). 


BNZ 

ERROR 


LOOP 

GET 

RPL=RETRVE 

Get previous record. 


LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


EOD 

EQU 

* 

Come here for end of data. 

ERROR 



Request failed. 

IN 

DS 

CL100 

Area for retrieved record. 


Example 3: Skip-Sequential Retrieval 

In this example, a GET macro is used to retrieve variable-length records 
synchronously. Records are to be processed in the I/O buffer. The search 
argument is full key, compared greatcr-than-or-equal; key length is eight bytes. 

The records are retrieved in key sequence, but some records arc skipped. 
Skip-sequential retrieval is similar to keyed-direct retrieval, except that you must 
retrieve records in ascending sequence (with skips) rather than in a random 
sequence. 

GENCB BLK=ACB, 

DDNAME=INPUT, 

MACRF=(KEY, 

SKP,IN) 

LTR 15,15 

Chapter 2. VS AM Macro Formats and Examples 87 


VSAM gets an area in 
virtual storage to generate 
the access method control 
block and returns the 
address in register 1. 



GET 



BNZ 

CHECKO 



LR 

2,1 



GENCB 

BLK=RPL, 

ACB=(2), 

AREA=RCDADDR, 

AREALEN=4, 

ARG=SRCHKEY, 
OPTCD=(KEY,SKP, 
SYN,NUP,KGE, 
FKS,LOC) 

• 


LTR 

15,15 



BNZ 

CHECKO 



LR 

3,1 

Address of the request 
parameter list. 

LOOP 

MVC 

GET 

SRCHKEY,source 

RPL=(3) 

Search argument for 
retrieval, moved in from 
a table or a transaction 
record. 


LTR 

15,15 



BNZ 

ERROR 



SHOWCB 

AREA=RCDLEN, 

FIELDS=RECLEN, 

LENGTH=4, 

RPL=(3) 

Display the length of the 
record. 


LTR 

15,15 



BNZ 

CHECKO 



B 

LOOP 


ERROR 



Request was not accepted, 
or failed. 

CHECKO 

• • • 


Generation or display 


failed. 


{ 


RCDADDR DS F 


SRCHKEY DS CL8 


Work area into which VSAM puts 
the address of a data record 
within the I/O buffer 
(OPTCD=LOC). 

Search argument for retrieval. 


RCDLEN DS F 


For displaying variable record 
lengths. 


The macros and instructions are as follows: 
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• The first GENCB generates an access method control block, which specifies 
keyed, skip-sequential, and input processing. The address of the access 
method control block is stored in register 2. 

• The second GENCB generates a request parameter list. The address of the 
request parameter list is stored in register 3. 

• MVC moves the search argument into SRCI1KEY, the area defined for the 
search argument. 

• GET specifies that the record pointed at by the request parameter list whose 
address is in register 3 is to be retrieved. Records are retrieved by a 
skip-sequential search through the sequence set of the index. 

Example 4: Addressed-Sequential Retrieval 

In this example, one GET macro is used to retrieve multiple fixed-length, 20-byte 

records. The records are moved to a work area (only option). 

BLOCK ACB DDNAME=INPUT, 

MACRF=(ADR,SEQ, 

IN) 

GENCB BLK=RPL, 

COPIES=10, 

ACB=BLOCK, 

OPTCD=(ADR,SEQ, 

SYN,NUP,MVE) 


LTR 

15,15 


BNZ 

CHECKO 


LA 

3,10 

Number of lists(10). 

LR 

ro 

w 

Address of the first list. 

LR 

1,0 

Length of all of the lists. 
Registers 0 and 1 contain 
length and address of the 
generated control blocks 
when VSAM returns control 
after GENCB. 

SR 

0,0 

Prepare for following division 

DR 

0,3 

Divide number of lists into 
length of all the lists. 

LR 

3,1 

Save the resulting length of a 
single list for an offset. 

LR 

4,2 

Save address of the first 
list. 

LA 

5,RECAREA 

Address of the first work 
area. 


Do the following 6 
instructions 10 times to set 
up all the request parameters 
lists. The 10th time, register 
4 must be set to 0 to indicate 
the last request parameter 
list in the chain. 
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LOOP 


AR 

4,3 

Address the next list. 

MODCB 

RPL=(2), 
NXTRPL=(4), 
AREA=(5), 

AREALEN=20 

In each request parameter list, 
indicate the address of the 
next list and the address and 
length of the work area. 

LTR 

15,15 


BNZ 

CHECKO 


AR 

2,3 

Address the next list. 

LA 

5,20(5) 

Address the next work area. 
Restore register 2 to address 
the first list before continuing 
to orocess. 

GET 

RPL=(2) 


LTR 

15,15 


BNZ 

ERROR 

Process the 10 records that 
have been retrieved by the 

GET. 

B 

LOOP 



CHECKO ... 


ERROR 


RECAREA DS CL200 


Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find out 
which one had an error. 

Space for a work area for each 
of the 10 request parameter 
lists. 


ITie GENCB macro generates 10 request parameter lists; the lists are 
subsequently chained together by using the MODCB macro to modify the 
NXTRPL parameter in each copy. Because SEQ is specified in each request 
parameter list and no previous request has been issued against the access method 
control block since it was opened, retrieval begins at the beginning of the data set. 
Each time the GET macro is executed, VSAM is positioned at the next record in 
RBA sequence. VSAM moves each record into the work area provided for the 
request parameter list that identifies the record. 

If an error occurred for one of the request parameter lists in the chain and you 
have supplied error-analysis routines, VSAM takes a LERAD or SYNAD exit 
before returning to your program. Register 15 is set to indicate the status of the 
request. A code of 0 indicates that no error was associated with any of the 
request parameter lists. Any other code indicates that an error occurred for one 
of the request parameter lists. You should issue a SHOWCB macro for each 
request parameter list in the chain to find out which had an error. VSAM 
doesn't process any of the request parameter lists except the one with an error. 
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Example 5: Sequential Retrieval for a Relative Record Data Set 


In this example, a GET macro is used to sequentially retrieve records by relative 
record number. Fixed-length, 100-byte records are moved to a work area. 
Processing is synchronous. 


INPUT 

ACB 

MACRF=(KEY,SEQ 
IN) 

RETRVE 

RPL 

ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

ARG=RCDNO, 

OPTCD=(KEY,SEQ 

SNY,NUP,MVE) 

LOOP 

GET 

RPL=RETRVE 


LTR 

15,15 


BNZ 

ERROR 


B 

LOOP 

ERROR 

... 


IN 

DS 

CL100 

RCDNO 

DS 

CL4 


All MACRF and OPTCD 
subparameters specified are 
defaults and could have been 
omitted. 


This GET or identical GETs 
can be issued, with no change 
in the RPL, to retrieve 
subsequent records in relative 
record number sequence. 


Request was not accepted or 
it failed. 


IN contains a data record 
af£er GET is ^compiatad. 

VSAM returns relative record 
number of retrieved record in 
this field. 


The records arc retrieved in relative record number sequence. Empty records are 
bypassed for sequential retrieval. A 4-byte search argument must be specified. 
The relative record number of each record retrieved is stored in the search 
argument. VSAM is positioned at the first relative record when the data set is 
opened, and the next nonempty record is retrieved automatically as each GET is 
issued. The branch to ERROR would also be taken if the end of the data set is 
reached. 
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Example 6: Keyed-Direct Retrieval 

In this example, a GET macro is used to retrieve fixed-length, 100-byte records 
directly by key. The key length is 15 bytes; the search argument is a 5-byte 
generic key, compared equal. The control blocks are generated at assembly. 

INPUT ACB MACRF=(KEY, 

DIR,IN) 

RETRVE RPL ACB=INPUT, You specify all parameters for 

AREA=IN, the request in the RPL macro. 

AREALEN=4, 

OPTCD=(KEY, 

DIR,SYN,NUP, 

KEQ,GEN,LOC), 

ARG=KEYAREA, 

KEYLEN=5 


LOOP MVC KEYAREA,SOURCE Search argument for retrieval, 

moved in from a table or a 
transaction record. 

GET RPL=RETRVE This GET or identical GETs can 

be issued with no change in the 
RPL: Specify each new search 
argument in the field KEYAREA. 

LTR 15,15 

BNZ ERROR 

. Process the record. t 

\ 


B LOOP 

ERROR ... Request was not accepted, or 

. failed. 


IN DS CL4 VSAM puts here the address of 

the record within the I/O 
buffer. 

KEYAREA DS CL5 You specify the search argument 

here. 


The generic key specifics a class of records. For example, if you search on the 
first third of employee number, VSAM positions at and retrieves the first of 
presumably several records that start with the specified characters. To retrieve all 
the records in that class, either switch to sequential access or to a full-key search 
with a greater-than-or-cqual comparison. 
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Example 7: Addrcsscd-Direct Retrieval 


In this example, a GET macro is used to retrieve fixed-length 20-byte records. 
The records are to be moved to a work area. 


BLOCK 

ACB 

DDNAME=INPUT, 
MACRF=(ADR, DIR, 
IN) 

Access method control 
block generated at 
assembly. 


GENCB 

BLK=RPL, 

C0PIES=1, 
ACB=BLOCK, 
OPTCD=(ADR, DIR, 
SYN, NUP, MVE) 

ARG=SRCHADR, AREA=IN, 
AREALEN=20 

Request parameter list 
generated at execution. 


LTR 

15,15 



BNZ 

CHECKO 



LR 

2, 1 

Address of the list. 

LOOP 

MVC 

GET 

SRCHADR, 

RPL=(2) 

Search argument for 
retrieval; calculated or 
moved in from a table or 
a transaction record. 


LTR 

15, 15 



BNZ 

ERROR 



Process the record. 


B LOOP 


CHECKO 


Generation failed. 


ERROR 


Request was not accepted, 
or failed. 


IN DS CL20 


VSAM puts a record here 
for each GET request. 


SRCHADR DS CL4 


You specify the RBA 
search argument here for 
each request. 


The RBA provided for a search argument must match the RBA of a record. 
Keyed insertion and deletion of records in a key-sequenced data set will probably 
cause the RBAs of some records to change. Therefore, if you process a 
key-sequenced data set by addressed-direct access (or by addressed-sequential 
access using POINT), you need to keep track of changes. You can use the 
JRNAD exit for this purpose. See “EXLST Macro (Generate an Exit List at 
Assembly Time)” on page 66. 
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Example 8: Switch from Direct to Sequential Retrieval 

In this example, GET macros are used to retrieve fixed-length, 100-byte records. 
The retrieval is via an alternate index path defined with the nonunique key 
option. Every time a nonunique key is retrieved, the program switches to 
sequential processing to retrieve the other records with the same key. The 
control blocks were generated at assembly, but the MODCB macro is used to 
modify the request pjirameter list to permit switching from keyed-direct to 
keyed-sequential retrieval. For the direct request preceding sequential requests, 
the search argument is an 8-byte, generic key, compared equal. Positioning is 
requested for direct requests. 


INPUT 

ACB 

MACRF=(KEY,DIR, 
SEQ,IN) 

Both direct and 
sequential access 
specified. 

RETRVE 

RPL 

ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

OPTCD=(KEY,DIR, 

SYN,NSP,KEQ, 

GEN„MVE), 

ARG=KEYAREA, 

KEYLEN=£ 

NSP specifies that VSAM 
is to remember its 
position. 

LOOP 

L00P1 

M¥€ 

GET 

KEYAREA,source 

RPL=RETRVE 

Search argument for 
direct retrieval; moved 
in from a table or a 
transaction record. 


LTR 

15,15 



BNZ 

ERROR 



SHOWCB 

RPL=RETRVE, 

AREA=FDBAREA, 

FIELDS=FDBK 

Extract feedback 
information. 


LTR 

15,15 



BNZ 

ERROR 



CLI 

ERRCD, 8 

Does a duplicate key 
follow? 


BE 

SEQ 

Yes; retrieve duplicates 
sequentially. 


B 

LOOP 

No; retrieve next record 
in direct mode. 

SEQ 

MODCB 

RPL=RETRVE, 
OPTCD=SEQ 

Alter request parameter 
list for sequential 
access. 


LTR 

15,15 



BNZ 

CHECKO 
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SEQGET 

GET 

RPL=RETRVE 

Do sequential retrieval. 


LTR 

15,15 

Test for error. 


BNZ 

ERROR 



SHOWCB 

RPL=RETRVE, 

AREA=FDBAREA, 

FIELDS=FDBK 

Extract feedback 
information. 


LTR 

15,15 



BNZ 

ERROR 



CLI 

ERRCD, 8 

Does a duplicate key 
follow? 


BE 

SEQGET 

Yes; retrieve 
sequentially. 

DIR 

MODCB 

RPL=RETRVE, 
OPTCD=DIR 

Alter request parameter 
list for direct access. 


LTR 

15,15 



BNZ 

CHECKO 



B 

LOOP 

Prepare new search 
argument. 

ERROR 



Request was not accepted, 
or failed. 

CHECKG 

# 


Modification failed. 

IN 

DS 

CL100 

VSAM puts retrieved 
records here. 

KEYAREA 

DS 

CL8 

Specify the generic key 
for a direct request 
here. 

FDBAREA 

DS 

OF 

Feedback area for SHOWCB. 


DS 

1C 

Reserved. 

TYPECD 

DS 

1C 

Error type code. 

CMPCD 

DS 

1C 

Component code. 

ERRCD 

DS 

1C 

Reason code. 


Positioning is associated with a request parameter list; the MODCB macro is 
used to modify a single request parameter list that alternately defines requests for 
both types of access rather than use a different request parameter list for each 
type. 

With direct retrieval, VSAM doesn't remember its position for subsequent 
sequential retrieval unless you explicitly request it (OPTCD= NSP or UPD). 
After a direct GET for update, VSAM is positioned for a subsequent PUT, 
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ERASE, or sequential GET. If you modify OPTCD= (DIR,NUP) to 
OPTCD = SEQ, you must issue POINT to get VSAM positioned for sequential 
retrieval, as NUP indicates that no positioning is desired with a direct GET. 

If you have chained many request parameter lists together, one position is 
remembered for the whole chain. For example, if you issue a GET that gives the 
address of the first request parameter list in the chain, the position of VSAM 
when the GET request is complete is at the record following the record defined 
by the last request parameter list in the chain. Therefore, modifying 
OPTCD = (DIR,NSP) in each request parameter list in a chain to 
OPTCD = SEQ implies continuing with sequential access relative to the last of 
the direct request parameter lists. 
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GETIX Macro (Retrieve an Index Record) 

The format of the GETIX macro is: 


| label\ 


GETIX 


RPL = address 


where: 

label 

is 1 to 8 characters that provide a symbolic address for the GETIX macro. 
RPL = address 

specifies the address of the request parameter list that defines this GETIX 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 

The following RPL parameters and subparameters are required for GETIX: 

OPICD = (CNV 
,DIR 

,{N UP | UPI) 1NSP} 

,{LOC|MVE}) 

GETIX can be issued either for update or not for update; 

OPTCD= NSP is interpreted as OPTCD= NUP. 

With OPTCD = MVE, AREALEN must be at least index control 
interval size. 

ARG = address 

The search argument for GETIX is the RBA of a control interval. 

To process the index of a key-sequenced data set with GETIX, you must open 
the cluster with: 

ACB MACRF=(CNV,... ) 
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MNTACQ Macro (Mount Acquire) 

The format of the MNTACQ macro is: 

\label\ _ MNTACQ RPL = address _ 

RPL = address 

specifies the address of the RPL that identifies your opened VS AM data set 
and your arguments. The following RPL parameters have meaning for 
MNTACQ: 

ACB = address 

identifies your VSAM data set. 

ARG = address 

identifies your arguments, address points to a parameter list, aligned 
on a fullword boundary as follows: 


Offset Length Contents 

0 4 Feedback area: address of an 

FCB WAIT list 

4 6 VOLSER, target volume 

10 1 Reserved 

11 1 Argument entry count (N) 

(N = 1 to 255) 

12 4N Argument entries 

12+4{N-l) 4 RBA for which an ACQUIRE is 

requested 

The maximum number of arguments is 255. 

For the specified list, MNTACQ will acquire (stage) the data cylinders 
corresponding to each RBA for the one given volume, ITie volume 
will be mounted if necessary. 

OPTCD = ({ADR | KEY} 

,{ASY|SYN} 

,{KEQ|KGE) 

,FKS) 

ADR is valid for entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 
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KEY is valid for key-sequenced data set and relative record data set, 
error for entry-sequenced data set. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 

GEN is not supported; if specified, it will give an error indication. 

All other OPTCD parameters are not applicable, and, if specified, are 
ignored with no error indication. 

Because your request may result in the staging of numerous cylinders, a single 
ECB is not sufficient for an asynchronous MNTACQ request. The RPLECB 
field is inoperative for the MNTACQ interface. Upon return from an 
asynchronous MNTACQ, the feedback area of the MNTACQ parameter list will 
contain the address of a standard ECB WAIT list. You must then use this list in 
conjunction with the WAIT macro or you may use the list in conjunction with 
the EVENTS macro of MVS. An asynchronous request must conclude with 
either CHECK, ENDREQ, or CLOSE. 

At the conclusion of this macro, the RPL is disconnected in a manner similar to 
that of a direct VSAM request. Any positioning in effect prior to execution of 
this macro will be lost. You may have to renosition. Chained RPLs are not 
supported by MNTACQ. 
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MODCB Macro (Modify an Access Method Control Block) 

The format of the MODCB macro used to modify an access method control 
block is: 


l label] 


MODCB 


ACB = address 
[BvSTRNO = number] 
j,BUFND = number] 

|,BUFNI = number] 
j,BUFSP = number] 

|,CATALOG = YESJNOl 
f,CRA = SCRA|UCRA| 

(,DDNAME = ddname | 

|,EXLST = address] 

|,MACRF = ([ADR|I,CNV|I,KEYI 
(,CFX|NFXI 
|,DDN|DSN| 

|,DFR|NDF| 

|,DIR|I,SEQ||,SKPI 

|,ICI|NCT| 

I,IN||,OUT| 

!,MS|S1S| 

|,NRM|AIX| 

hNRSlRSTl 

f,NSR|LSR|GSR| 

I,NUB|UBF|)| 

|,MAREA = address | 

|,MLEN = number] 

|,PASSWD = address] 

|,RMODE3I = fALLlBUFFICBI NONEl l 
|,SllRPOOL = number] 

|,STRNO = number] 


Note: The RMODE31 parameter replaces the AMODE31 subparameter shown 
in previous releases. 

The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

label 

is l to 8 characters that provide a symbolic address for the MODCB macro. 
ACB = address 

specifies the address of the access method control block to be modified. 

The data set identified by the access method control block must not be 
opened. A request to modify the access method control block of an open 
data set will fail. 
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Note: The remaining parameters represent parameters of the ACB macro that 
can be modified. The value specified replaces the value, if any, presently in the 
access method control block. There are no defaults. For an explanation of these 
parameters, see “ACB Macro (Generate an Access Method Control Block at 
Assembly Time)” on page 34. 

If MODCB is used to modify a MACRF subparameter, other subparameters are 
unaffected, except when they are mutually exclusive. For example, if you specify 
MACRF = ADR in the MODCB and MACRF = KEY is already indicated in the 
control block, both ADR and KEY will now be indicated. But, if you specify 
MACRF * UBF in the MODCB and NUB is indicated, only UBF will now be 
indicated. 

The RMODE31 parameter tells the VSAM OPEN routines where to obtain 
storage for the control blocks and I/O buffers. Therefore, the only time the 
values specified by the RMODE31 parameter have any effect on VSAM is on the 
setting just before an OPEN is issued. At other times, changing these values has 
no effect on the residency of the control blocks and I/O buffers. 

If MODCB RPL is used to change the address of an ACB, you must first issue 
an ENDREQ macro. 

Example: MODCB Macro (Modify an Access Method Control Block) 

In this example, a MODCB macro is used to modify the name of the exit list in 
an access method control block. 

MODCB ACB=BLOCK, BLOCK was generated at 

EXLST=EGRESS assembly. 
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MODCB Macro (Modify an Exit List) 

The format of the MODCB macro used to modify an exit list is: 


\label\ 


MODCB 


EXLST » address 
(,EODAD - (\address\\,A | N|(,L|)| 
|,JRNAD = ([a^r^|[,A|N|[,L|)| 
(,LERAD =* (\address\\,A | N||,L|) j 
|,SVNAD = (\address%A | N||,L|)| 


The subparameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

label 

is 1 to 8 characters that provide a symbolic address for the MODCB macro. 

EXLST ^address 

specifies the address of the exit list to be modified. You can modify an exit 

list at any time—that is, before or after opening the data set(s) for which the ( 

list indicates exit routines. You cannot, however, add an entry to the exit 

list if it will change the exit list's length; the exit list must already be large 

enough to contain the new exit address. The order in which addresses are 

stored in the EXLST control block is: EODAD, SYNAD, LERAD, 

JRNAD, and UPAD. For example, if you generate an exit list with only 
the LERAD exit, you can add entries for EODAD and SYNAD later; you 
cannot add the JRNAD exit address, because doing so would increase the 
size of the EXLST control block. The MODCB macro does not support 
the UPAD user exit. 

Note: If the JRNAD exit is changed for an OPEN ACB, then the ACB 
must be closed and reopened in order to use the modified JRNAD exit. 

For more information about user exit routines sec Data Facility Product: 

Customization. 

The remaining parameters represent parameters of the EXLST macro that can be 
modified or added to an exit list. For an explanation of these parameters, see 
“EXLST Macro (Generate an Exit List at Assembly Time)” on page 66. 


102 MVS/XA VSAM Administration: Macro Instruction Reference 







MODCB—EXLST 


Example: MODCB Macro (Modify an Exit List) 


In this example, a MODCB macro is used to activate an exit in an exit list. 


MODCB 

EXLST=(*. 
EXLSTADR), 

Indirect notation is used 


to specify the address of 
the exit list, which was 

E0DAD=(E0D,L,A) 

. 

generated at execution. 

• 

• 

EOD DC 

C*ENDUP’ 


EXLSTADR DS 

F 

When the exit list was 



generated, its address was 
saved here. 


The MODCB macro's parameters are: 

• EXLST specifics that the address of the exit list to be modified is located at 
EXLSTADR. 

• EODAD specifics that the entry for the end-of-data routine is to be marxed 
active in the exit list whose address resides at EXLSTADR. The name of the 
end-of-data routine, ENDUP, is located at EOD. 
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MODCB Macro (Modify a Request Parameter List) 

The format of a MODCB macro used to modify a request parameter list is: 


[label] 


MODCB 


RPL = address 
|,ACB = address | 

(,AREA = address] 
j.AREALEN = number] 

(,ARG = address] 

= address] 

|,KEYLEN = number] 
fjMSGAREA = address] 
|,MSGLEN ~ number] 
|,NXTRPL = address] 

|,OPTCD - (|ADR|CNV|KEYJ 
|,DIR|SEQiSKP| 
[,ARD|LRD| 
|,FWD|B\VD| 
(,ASY|SYN| 
|,NSP|NUP|LPD| 
(,KEQ|KGE) 
I,FKS|GEN| 
|,LOC|MVE|)| 
f,RECEEN = number] 

[,TR ANSID = number] 


The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 


label 

is 1 to 8 characters that provide a symbolic address for the MODCB macro. 
RPL * address 

specifics the address of the request parameter list to be modified. You may 
not modify an active request parameter list; that is, one that defines a 
request that has been issued but not completed. To modify such a request 
parameter list, you must first issue a CHECK or an ENDREQ macro. 

Note: The remaining parameters represent parameters of the RPL macro that 
can be modified. The value specified replaces the value, if any, presently in the 
request parameter list. There are no defaults. For an explanation of these 
parameters, see “GENCB Macro (Generate a Request Parameter List at 
Execution Time)” on page 80. 

If MODCB is used to modify an OPTCD subparameter within a group of 
subparameters, the current subparameter for that group is changed, because only 
one subparameter in a group is effective at a time. Only the OPTCD 
subparameter specified is changed; all other OPTCD subparameters remain 
unchanged. 
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Example: MODCB Macro (Modify a Request Parameter List) 

In this example, a MODCB macro is used to modify the record length field in a 
request parameter list. 

Note: This example also shows the one exception to GENCB, MODCB, 
SHOWCB, and TESTCB building a parameter list and passing it to the control 
block manipulation module in register 1. In this example, the RPL address (in 
register 2) would be loaded into register 1 and the RECLEN value (in register 3) 
would be loaded into register 0. These registers would be passed to the control 
block manipulation macro. This will occur if the LIST, EXECUTE, or 
GENERATE form of the MODCB macro is not used and the only parameter 
specified, besides RPL, is RECLEN. 

L 3,length Load the new record length. 

MODCB RPL=(2), Register 2 contains the address 

of the request parameter list. 

RECLEN=(3) Register 3 contains the record 
length. 


The MODCB macro's parameters are: 

• RPL specifies that register 2 contains the address of the request parameter list 
to be modified. 

• RECLEN specifies that the record length field is to be modified. The 
contents of register 3 will replace any current value in the RECLEN field. 
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MRKBFR Macro (Mark Buffer) 

The format of the MRKBFR macro is: 


MRKBFR 


MARK = {DINVALID|XINVALID|Oirr|RLS} 
,RPL = address 


MARK= {DINVALID|XINVALID|OUT|RLS) 

specifies whether to mark for output or to release from exclusive control or 
shared status the buffer identified in the RPL. To do both, issue 
MRKBFR twice, once with MARK = OUT, again with MARK = RLS. 

DINVALIDIXINVAUD 

specifies whether to mark the data component or index component 
buffers invalid. The buffers to be invalidated are identified as those 
which contain records, whose RBA values are within the RBA range 
pointed to by the RPL ARG address. DINVALID specifies that the 
data component buffers are to be marked invalid; XINVALID 
specifies that the index component buffers are to be marked invalid. 


OUT 

indicates that the buffer is to be marked for output. The buffer is 
kept under exclusive control or in shared status. 


RLS 

indicates that the buffer is to be released from exclusive control or 
shared status. 

RPL = address 

specifies the address of the request parameter list that defines the 
MRKBFR request. Use the RPL used by SCIIBFR or GET to locate the 
buffer being marked or released. These RPL parameters have meaning for 
MRKBFR: 

ACB = address 


ARG = address 

I The address of the 8-bytc field that contains the beginning and ending 

I RBAs of the range to be searched on. 

EC B = address 


TRANSID = number 

All other RPL parameters are ignored. RPLs are assumed not to be 
chained. OPTCD= LOC is assumed. 

If the ACB to which the RPL is related has MACRF = GSR, the 
program that issues MRKBFR must be in supervisor state with 
protection key 0 to 7. 
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I OPEN Macro (Connect Program and Data) 

The format of the OPEN macro is: 


\label\ 

OPEN 

(address,{(options)],...) 



I,MOI)E = {24|31)| 


label 

is 1 to 8 characters that provide a symbolic address for the OPEN macro. 
address 

| specifics the address of the ACB or DCB for the data sct(s) to be opened. 

You may specify the address in register notation (using a register from 2 
through 12, in parentheses) or specify it with an expression that generates a 
valid relocatable A-type address constant. If you use register notation to 
open only one data set, you must enclose the expression identifying the 
register in two sets of parentheses: for example, OPEN ((2)). 

options 

arc options parameters for use only in opening non-VSAM data sets. If 
any options arc specified with the address of an access method control 
block, VSAM ignores them. 

MODE - 

specifies the format of the OPEN parameter list that is to be generated. 

24 

specifics that a standard form (24-bit) parameter list address is to be 
generated. The parameter list must reside below 16 megabytes and 
point to an ACB residing below 16 megabytes. Phis is the default 
parameter. 

31 

specifies that a long form (31-bit) parameter list address is to be 
generated. This parameter value must be coded if the parameter list 
or the VSAM/VTAM ACB resides above 16 megabytes. 

Note: If the VSAM control blocks and buffers are to reside above 16 megabytes, 
the RMODE31 parameter must be specified in the ACB before the OPEN is 
issued. 

Because the OPEN parameters are positional, include a comma for options (even 
if you don't specify options) before a subsequent parameter. 
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Example 1: OPEN Macro used to open two data sets. 

In this example, the access method control block for one data set was generated 
at execution; the other was generated at assembly. 

GENCB BLK=ACB, An access method control block. 

DDNAME=DATA 

LTR 15,15 

BNZ ERROR 


LR 2,1 

OPEN (BLOCK,,(2)) 


BLOCK ACB 


Address of the control block. 

A label is used for the access 
method control block generated 
by ACB; register notation is used 
for the one generated by GENCB. 
The two commas indicate the 
omission of options. 

Another access method control 
block. 


| Example 2: OPEN Macro with a parameter list above 16 megabytes. 


| This example shows a program being opened with a parameter list that may 

| reside above 16 megabytes. 

| OPLSTA OPEN M0DE=31, 

f MF=(E,OPLSTB) 

| OPLSTB OPEN (ACB1,,ACB2), 

| M0DE=31, 

I MF=L 


| Since MODE = 31 is coded in the list form of the OPEN macro, VSAM ACBs 

| and the OPEN parameter list may reside above 16 megabytes. 

| Note: Consistency must be maintained while using the MODE operand in the 

| MF = L and MF = E versions of the OPEN macro. If MODE = 31 is specified in 

| the MF = L version, then MODE = 31 must also be coded in the corresponding 

| MF= E version of the macro. Unpredictable results may occur if this rule is not 

| followed. 

| MF = E and MF = L arc not required. OPEN (ACB 1), MODE = 31 is also valid. 
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POINT Macro (Position for Access) 


The format of the POINT macro is: 


| Iabel\ 


POINT 


RPL = address 


label 

is 1 to 8 characters that provide a symbolic address for the POINT macro. 
RPL = address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 


Example: Position with POINT 

In this example, the POINT macro is used to position at a record identified by a 
full key (5-byte) search argument, compared equal. 
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POINT 


BLOCK 

ACB 

DDNAME=I0 

POSITION RPL 

ACB=BL0CK, 
AREA=W0RK, 
AREALEN=50, 
ARG=SRCHKEY, 
0PTCD=(KEY,SEQ 

LOOP 

MVC 

SRCHKEY, source 


POINT 

RPL=P0SITI0N 


LTR 

15,15 


BNZ 

ERROR 

L00P1 

GET 

RPL=P0SITI0N 


LTR 

15,15 


BNZ 

ERROR 


Default MACRF subpararaeters 
sufficient. 

AR6 parameter and KEQ and 
FKS OPTCD subparameters 
define the POINT request. 

SYN,KEQ,FKS) 


Search argument for 
positioning, moved in from 
a table or a transaction 
record. 


Process the record. Decide whether to skip to another 
position (forward or backward). 


BE LOOP 

B L00P1 

ERROR 

SRCHKEY DS CL5 

WORK DS CL50 


Yes; skip. 

No; continue in 
consecutive sequence. 

Request was not accepted, 
or failed. 

Search argument for 
positioning. 

VSAM puts a record here 
for each GET request. 
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PUT Macro (Store a Record) 

The format of the PUT macro is: 


| labeH 


PUT 


RPL = address 


label 

is 1 to 8 characters that provide a symbolic address for the PUT macro. 
RPL = address 

specifics the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: If the PUT macro is being used to load records into an empty data set, 
the STRNO value in the access method control block must be 1, and RPL 
OPTCD = DIR must not be specified. However, for an empty relative record 
data set, DIR is allowed. 

Example 1: Keyed-Sequential Insertion 

In this example, a PUT macro is used to perform keyed-sequential insertion. 
Variable-length records with a key length of 15 bytes are to be moved from a 
work area. Some records will be inserted between existing records; other records 
will be added at the end of the data set. 


BLOCK 

ACB 

BDNAME=OUTPUT, 

MACRF=(KEY,SEQ,OUT) 

LIST 

RPL 

ACB=BLOCK, 
AREA=BUILDRCD, 
AREALEN=250, 
OPTDC=(KEY,SEQ, 
SYN,NUP,MVE) 


LOOP 

L 

2,source 

Put length of record to 
be inserted into 
register. 


MODCB 

RPL=LIST, 

RECLEN=(2) 

Indicate record length 
in request parameter 
list. 


LTR 

15,15 



BNZ 

CHECKO 



PUT 

RPL=LIST 



LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


CHECKO 



Modification failed. 
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ERROR 



Request was not accepted, 
or failed. 

BUILDRCD DS 

CL250 

Work area for building 
records. 

The request parameter list, LIST, is associated with the access method control 
block, BLOCK. The length of each record to be inserted is put into register 2, 
which is subsequently used by MODCB to change the record length in the 
request parameter list. The record length is, therefore, correctly indicated in the 
request parameter list before the PUT macro is issued. The execution of the 

PUT macro causes VSAM to skip ahead (never back) to the next record. 

Example 2: Recording RBAs When Loading 



In this example, a PUT macro is used to record the RBAs of records as they are 
loaded into a key-sequenced data set. The RBAs are recorded in a table with 
20-byte entries (4 bytes for RBA, 15 bytes for associated key, and 1 byte of 
padding so the next entry begins on a fullword boundary). 


LA 

3,RBATABLE 

Address of the beginning of 
the table. 

LOOP 

i 

2,source 

Put length of record to be 
inserted into register 2. 


MODCB RPL=LIST, 
REGLEN=(2> 

Indicate record length in 
request parameter list. 


LTR 

15,15 



BNZ 

CHECKO 



PUT 

RPL=LIST 



LTR 

15,15 



BNZ 

ERROR 



SHOWCB AREA=(3), 

FIELDS=RBA, 

LENGTHS, 

RPL=LIST 

Each SHOWCB puts a record's 
RBA into the table. 


LTR 

15,15 



BNZ 

CHECKO 



MVC 

4(15,3), 

keyfield 

Put the record's key field 
in the table. 


LA 

3,20(3) 

Point to the next entry. 


B 

LOOP 


ERROR 



Request was not accepted, 
or failed. 
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CHECKO 


Modification or display 
failed. 


RBATABLE 

DSECT 

DS 

OF 

Get enough virtual storage 
for as many table entries 
as there are records in 
the data set. 

RBA 

DS 

CL4 


KEY 

DS 

CL15 



DS 

CL1 

Padding to keep each RBA 


entry on a fullword 
boundary: SHOWCB's display 
area must be on a fullword 
boundary. 

The need to process a key-sequenced data set by address should be unusual, but 
by recording the RBA of each record in a key-sequenced data set, you have 
search arguments for possible processing of the data set by addrcssed-direct 
retrieval and by addressed-sequential retrieval using the POINT macro. (You 
don't need to know RDAs to process a key-sequenced data set by simple 
addressed-sequential retrieval, since you go from the beginning without any 
skips.) 


You can display the RBA of a record after you issue a GET or a POINT, as well 
as after you issue a PUT. 

Example 3: Loading a Relative Record Data Set (Skip-Sequential and Direct Processing) 


In this example, a PUT macro is used to store twenty 100-byte records in slots 5, 
10, 15,...,100 of the data set. MODCB is used to switch to direct processing, and 
a PUT is used to store records in slots 26 and 51 of the data set. 


OUTACB 


ACB 

MACRF=(SKP,OUT, 
DIR,KEY) 


GENCB 

BLK=RPL, 

ACB=OUTACB, 

AREA=W0RK, 

AREALEN=100, 

ARG=RCDN0, 

0PTCD=(KEY,SKP) 

Generate a request 
parameter list at 
execution time. 

LTR 

15,15 


BNZ 

GENFAIL 


LR 

5,0 

Save length of RPL. 

LR 

6,1 

Save address of RPL. 

LA 

7,5 

Initialize increment 
value. 

ST 

7,RCDNO 

Initialize argument to 
slot 5. 

LA 

10,20 

Initialize loop counter. 
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LOOP 

• • • 


Move new record into work. 


PUT 

RPL=(6) 

Store record. 


LTR 

15,15 



BNZ 

PUTERR 

Request was not accepted, 
or failed. 


L 

1,RCDNO 



AR 

1,7 



ST 

1,RCDNO 

Increment argument by 5. 


BCT 

10,LOOP 



MODCB 

RPIr=(6) , 

Switch to direct processing 



OPTCD=(DIR,KEY) 

to store records in slots 

51 and 26. 


LTR 

15,15 



BNZ 

GENFAIL 



LA 

7,51 



ST 

7,RCDNO 

Initialize argument to slot 
51. 


... 


Move new record into WORK. 


PUT 

RPL=(6) 

Store record in slot 51. 


LTR 

15,15 



BNZ 

PUTERR 

Request was not accepted, 
or failed. 


LA 

7,26 



ST 

7,RCDNO 

Initialize argument to slot 
26. 




Move new record into WORK. 


PUT 

RPL=(6) 

Store record in slot 26. 


LTR 

15,15 



BNZ 

PUTERR 

Request was not accepted, 
or failed. 


B 

RETURN 


GENFAIL 



Generation or modification 
failed. 

PUTERR 



PUT request was not 
accepted, or failed. 

RETURN 

... 


Terminate program. 

WORK 

OS 

CL100 

100-byte work area that 
contains record to be 




stored by PUT macro. 

RCDNO 

DS 

CIA 

4-byte relative record 
number. 
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Both skip-sequential and direct processing can be used to create a relative record 
data set. The ACB is opened for output. The 4-byte search argument 
(RCDNO) indicates the slot number where the record is to be stored. 

Example 4: Kcycd-ScqucntiaJ Insertion (Relative Record Data Set) 

In this example, a PUT macro is used to insert twenty 100-byte records into 
empty slots of a previously loaded relative record data set. If the slot is empty 
when the PUT is issued, the record is stored and the slot number (returned in the 
argument field) is stored in a table. If the slot is not empty when the PUT is 
issued, a duplicate record error indication is returned. When a duplicate record is 
indicated, the PUT is reissued until the record is successfully stored in an empty 
slot in the data set. 


OUTACB ACB 

MACRF=(KEY,SEQ, 

OUT) 


GENCB 

BLK=RPL, 

ACB=OUTACB, 

AREA=W0RK, 

AREALEN=100, 

ARG=RCDNO, 

OPTDC=(KEY,SEQ) 

Generate a request parameter 
list. 

LTR 

15,15 


BNZ 

GENERR 


LR 

6,1 

Save the address of the RPL. 

LA 

4,RRNTABLE+80 

Initialize address of end of 
table. 

LA 

3,RRNTABLE 

Initialize index to relative 
record number table. 

WRITERCD ... 


Move record into work area. 

PUT 

RPL=(6) 


LTR 

15,15 


BZ 

STRCDNO 

Branch, if PUT is successful 

LA 

10,8 


CLR 

10,15 

Test for logical error. 

BNE 

PUTERR 


TESTCB RPL=(6),FDBK=8, 
ERET=TESTERR 

Test for duplicate record. 

BE 

B 

WRITERCD 

PUTERR 

Branch, if duplicate record, 
and try to store record in 
next slot. 
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STRDCNO 



MVC. 

0(4,3)RCDN0 

Store relative record 
number in RRNTABLE. 


LA 

3,4(3) 

Increment to next table 
entry. 


CLR 

3,4 



BE 

RETURN 

If table full, return to 
caller. 


B 

WRITERCD 

Write next record. 

GENERR 

• • • 


Error routine for GENCB 
macro. 

TESTERR 

• • • 


Error routine for TESTCB 
macro. 

PUTERR 

... 


Error routine for PUT 
macro. 

RETURN 

• • 


Return to caller or 
terminate program. 

RCDNO 

DS 

CIA 

4-byte relative record 
number (argument) field. 

RRNTABLE 

DS 

20F 

Relative record number 
table. 

WORK 

DS 

CL100 

100-byte work area that 
contains record to be 
stored by PUT macro. 


Each record is stored in the next available slot in the data set. When a record is 
successfully stored, its relative record number is recorded in a table. 


Example 5: Skip-Sequential Insertion 


In this example, one PUT macro is used to insert multiple fixed-length, 100-byte 
records. Records are to be moved asynchronously from a work area. 


OUTPUT ACB MACRF=(KEY,SKP, 
OUT) 


GENCB BLK=RPL, Generate 5 request 

C0PIES=5, parameter lists at 

ACB=OUTPUT, execution. 

AREALEN=100, 

OPTCD=(KEY,SKP, 

ASY,NUP,MVE), 

RECLEN=100 

LTR 15,15 

BNZ CHECKO 
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Calculate length of each list and use register notation with 
the MODCB macro to complete each list. 

MODCB RPL=(2), 

AREA=(3), 

NXTRPL=(4) 

LTR 15,15 

BNZ CHECKO 


Increase the value in each register and repeat the MODCB 
until all five request parameter lists have been completed. 
The last time, register 4 must be set to 0. 



• 



LOOP 

• 


Restore address of first 




list in register 2. 

Build 5 records in WORK. 


PUT 

RPL=(2) 

Register 2 points to the 
first request parameter 
list in the chain. The 
five records in WORK are 
stored with this one 


LTR 

15,15 

PUT request. 


BNZ 

NOTACCEP 



CHECK 

RPL=(2) 



LTR 

15,15 



BNZ 

ERRO 



B 

LOOP 


CHECKO 



Generation or modification 
failed. 

NOTACCEP 




ERROR 

• * • 


Display the feedback field 
in each request parameter 
list to find out which one 
had an error. 

WORK 

DS 

CL500 

Contains five 100-byte work 




areas. 


You give no search argument for storage: VSAM knows the position of the key 
field in each record and extracts the key from it. Skip-sequential insertion differs 
from keyed-direct insertion in the sequence in which records may be inserted 
(ascending nonconsccutive sequence versus random sequence) and in 
performance. 


With skip-sequential insertion, if you insert two or more records into a control 
interval, VSAM doesn't write the contents of the buffer to direct-access storage 
until you have inserted all the records. With direct insertion, VSAM writes the 
contents of the buffer after you have inserted each record. 
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Example 6: Keyed-Direct Insertion 


In this example, a PUT macro is used to move fixed-length, 100-byte records 
from a work area. 

OUTPUT ACB MACRF=(KEY,DIR, 

OUT) 

DIRECT RPL ACB=OUTPUT, 

AREA=WORK, 

AREALEN=100, 

OPTCD=(KEY,DIR, 

ASY,NUP,MVE), 

RECLEN=100 


LOOP PUT RPL=DIRECT 
LTR 15,15 
BNZ NOTACCEP 


CHECK RPL=DIRECT 
LTR 15,15 

BNZ ERROR 

B LOOP 

NOTACCEP ... 

ERROR 

WORK DS CL100 
The macros are as follows: 


Request was not accepted. 
Request failed. 

Work area. 


• ACB specifics that the data set, OUTPUT, into which records are to be 
inserted, is opened for keyed-direct, output processing. 

• RPL specifies that the record to be inserted into the OUTPUT data set 
resides in a 100-bytc area, WORK. 

VSAM extracts the key from the key field of each record found at WORK. 
Using keyed-direct access is similar to using skip-sequential access. 
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Example 7: Addrcsscd-Sequcntial Addition 

In this example, a PUT macro is used to add variable-length records to a data 
set. The data set is assumed to be an entry-sequenced data set, because records 
cannot be inserted into or added to a key-sequenced data set with addressed 


access. 




BLOCK 

ACB 

MACRF=(ADR,SEQ, 
OUT) 


LIST 

RPL 

ACB=BLOCK, 
AREA=NEVRCD, 
AREALEN=100, 
OPTCD=(ADR,SEQ, 
SYN,MVE) 


LOOP 



Build the record. 


L 

3,source 

Put the length of the 
record into register 3. 


MODCB 

RPL=LIST, 

RECLEN=(3) 

Indicate length of new 
record. 


LTR 

15,15 



BNZ 

CHECKO 



PUT 

RPL=LIST 



LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


CHECKO 

... 


Modification failed. 

ERROR 

. 


Request was not accepted, 
or failed. 

NEWRCD 

DS 

CL100 

Build record in this work 
area. 


Each record is stored in the next position after the last record in the data set. 

You do not have to specify an RBA or do any explicit positioning (with the 
POINT macro). Addressed addition of records is always identical to loading a 
data set: When additional space is required, VSAM extends the data set. 

ITic only difference between addressed-sequential and addresscd-direct addition is 
when the buffers are written to external storage. The buffer is written to external 
storage only when it is full for sequential addition; it is written after each record 
for direct addition. You cannot use direct storage to load records into a data set 
for the first time; you must use sequential storage. 
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Example 8: Keyed-Sequential Update 

In this example, GET and PUT macros are used to retrieve and update 
fixed-length, 50-byte records. Records are updated synchronously in a work area. 
This example requires the use of a work area because you cannot update a record 


in the I/O buffer. 



UPDATA 

ACB 

MACRF=(KEY,SEQ, 

OUT) 


LIST 

RPL 

ACB=UPDATA, 
AREA=W0RK, 
AREALEN=50, 
0PTCD=(KEY,SEQ, 
SYN,UPD,MVE) 

UPD indicates the record may 
be stored back (or deleted). 

LOOP 

GET 

RPL=LIST 



LTR 

15,15 



BNZ 

ERROR 


Decide 

whether to update the record. 


BE 

LOOP 

Do not update it; retrieve 
another. 

Do update the 

record. 



PUT 

RPL=LIST 

Store the record back. 


LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


ERROR 

• • • 


Request was not accepted, or 
failed. 

WORK 

DS 

CL50 

VSAM puts the retrieved record 
here. 


A GET for update (OPTCD = UPD) must precede a PUT for update. Besides 
retrieving the record to be updated, GET positions VSAM at the record retrieved, 
in anticipation of the succeeding update (or deletion). It is not necessary for you 
to store back (or delete) the record that you retrieved for update. VS A M's 
position at the record previously retrieved allows you to issue another GET to 
retrieve the following record. You cannot then, however, store back the previous 
record: The position for update has been forgotten because of the following GET. 
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Example 9: Keyed-Direct Update 

In this example, GET and PUT macros are used to retrieve and update records. 


The MODCB macro is used to modify record length (RECLEN) in the request 
parameter list when an update causes the record length to change. The 
maximum record length is 120 bytes. The search argument is a full key (5 bytes), 


compared equal. 



INPUT 

ACB 

MACRF=(KEY,DIR, 
OUT) 


UPDTE 

RPL 

ACB=INPUT, 
AREA=IN, 
AREALEN=120, 
OPTDC=(KEY,DIR, 
SYN,UPD,KEQ, 
FKS,MVE), 
ARG=KEYAREA, 
KEYLEN=5 

UPDTE indicates the record 
may be stored back 
(or deleted). 

Process input and get search argument into KEYAREA; proceed 
to retrieve a record. 

LOOP 

GET 

RPL=UPDTE 



LTR 

15,15 



BNZ 

ERROR 



SHOWCB 

RPL=UPDTE, 
AREA=RLNGTH, 
FIELDS=RECLEN, 
LENGTHS 

Display the length of the 
record. 


LTR 

15,15 



BNZ 

CHECKO 


Update the record. Does the update change the record's 
length? 


BE 

STORE 

No; length not changed. 


L 

5,length 

Yes; load new length into 
register 5. 


MODCB 

RPL=UPDTE, 

RECLEN=(5) 

Modify length indication 
in the request parameter 
list. 


LTR 

15,15 



BNZ 

CHECKO 


STORE 

PUT 

RPL=UPDTE 



LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 
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ERROR 


CHECKO 


Request was not accepted, or 
failed. 

Display or modification 
failed. 


IN DS CL120 

KEYAREA DS CL5 

RLNGTH DS F 


Work area for retrieving, 
updating, and storing a 
record. 

Search argument for 
retrieving a record. 

Area for displaying the 
length of a retrieved record. 


You cannot update records in the I/O buffer. A direct GET for update positions 
VSAM at the record retrieved, in anticipation of storing back (or deleting) the 
record. This positioning also allows you to switch to sequential access to retrieve 
the next record. When PUT is issued after a DIRUPD GET request, PUT 
causes VSAM to release exclusive control. 


You do not have to store back a record that you retrieve for update, but, if you 
do not store it back before another retrieval, the current updates are lost. 
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Example 10: Addresscd-Scqucntial Update 


In this example, GET and PUT macros are used to retrieve and update records in 
an entry-sequenced data set. The records arc variable in length, a maximum of 
200 bytes. The lengths of the records are not changed by update (the length of a 
record can never be changed by addressed access). 


ENTRY 

ACB 

MACRF=(ADR,SEQ 

ADRUPD 

RPL 

ACB=ENTRY, 
AREA=W0RK, 
AREALEN=200, 
0PTCD=(ADR,SEQ 
SYN,UPD,MVE) 

LOOP 

GET 

RPL=ADRUPD 


LTR 

15,15 


BNZ 

ERROR 


SHOWCB 

RPL=ADRUPD, 
AREA=RECLEN, 
FIELDS=RECLEN, 
LENGTH=4 


LTR 

15,15 


BNZ 

CHECKO 


PUT 

RPL=ADRUPD 


LTR 

15,13 


BNZ 

ERROR 


B 

LOOP 

ERROR 



CHECKO 

... 


WORK 

DS 

CL200 

RLNGTH 

DS 

F 


UPDTE indicates update (or 
deletion). 


Find out how long the record 
is. 


Request was not accepted, or 
failed. 

Display failed. 


Record-processing work area. 

Display area for length of 
records. 


If you have inactive records in your entry-sequenced data set, you may reuse the 
space they occupy by retrieving the records for update and restoring a new record 
in their place. 

With a key-sequenced data set, it is not possible to change the length of records 
by addressed update because the index is not used and VS AM could not split a 
control interval if required because of changing record length. 

Addrcssed-direct update varies from sequential update in the specification of an 
RBA for a search argument. 


Chapter 2. VS AM Macro Formats and Examples 123 



PUT 


Example 11: Marking Records Inactive 

In this example, GET and PUT macros are used to retrieve a record from an 
entry-sequenced data set and to mark it as inactive, (llie record is marked as 
inactive by putting a hexadecimal FF' in the first byte of a record.) The inactive 
record will not be sequentially retrieved except for update. 

ENTRYSEQ ACB MACRF=(ADR,DIR, 

OUT) 


LIST 

RPL 

ACB=ENTRYSEQ, 

AREA=RECORD, 

UPD indicates update; 
storing the record back 



AREALEN=100, 
OPTCD=(ADR, DIR, 
SYN,UPD,MVE), 

marked inactive. 


• 

ARG=RBAAREA 


LOOP 

GET 

RPL=LIST 



LTR 

15,15 



BNZ 

ERROR 


Decide 

whether 

you still want the 

data in the record. 


BE 

LOOP 

Yes; retrieve the next 
record. 


MV I 

RECORD,X’FF* 

No; flag the record 
inactive. 


PUT 

RPL=LIST 

Storing the record with 
an inactive indicator is 




equivalent to deletion 
for an entry-sequenced 
data set. 


LTR 

15,15 



BNZ 

ERROR 



B 

LOOP 


ERROR 

• • • 


Request was not accepted 
or failed. 

RECORD 

DS 

CL100 

Work area for marking 
records. 

RBAAREA 

DS 

F 

Search argument for 
retrieving the record. 


Records of an entry-sequenced data set can't be deleted. If a record loses its 
usefulness for your application, your program can mark it inactive by placing a 
unique flag in some conventional part of the record so that when your programs 
retrieve the record thereafter they can recognize and bypass it. You can use the 
space occupied by an inactive record by retrieving it for update and storing a new 
record in its place. 
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PUTIX Macro (Store an Index Record) 

The format of the PUTIX macro is: 


| label\ 


PUTIX 


RPL = address 


where: 

label 

is 1 to 8 characters that provide a symbolic address for the PUTIX macro. 
RPL = address 

specifies the address of the request parameter list that defines this PUTIX 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-typc address constant. 

The following RPL parameters and subparameters are required for PUTIX: 

OPICD = (CNV 
,1)IR 
,UPD 
,MVE) 

OPTCD= LOC is not allowed. 


AREALKN 

must be at least index control interval size. 

The contents of a control interval must previously have been retrieved for update 
by way of GETIX. 

To process the index of a key-sequenced data set with GETIX, you must open 
the cluster with: 

ACB MACRF=(CNV,...) 
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RPL Macro (Generate a Request Parameter List at Assembly Time) 

The format of the RPL macro is: 


\labet[ 

RPL 

[ACB = address | 

I.AM = VSAMI 
|,AREA = address ) 

|,AREALEN — number] 

|,ARG = address\ 
j,ECB = address | 

[,KEYLEN » number] 

|,MSG AREA — address] 

|,MSGLEN — number] 

|,NXTRPL — address\ 

I.OPTCD « (IADR1CNVIKEY1 



f.DIRISEQISKPI 

(,ARD|LRD| 

|,FYVI>|BYVD| 

LASY1SYN1 

|,NSP|MP|LPD| 

|,KEQ1KGEI 

[,FKS|GEN[ 

I,WVAITX|VVAITX| 

|,LOC|MVE|)| 

- 


},RECLEN= number^ 
l/IRANSID = number] 


Values for RPL macro parameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

label 

is 1 to 8 characters that provide a symbolic address for the request 
parameter list that is generated. You can use it in the request macros to 
give the address of the list. You can use it in the NXTRPL parameter of 
the RPL macro, when you are chaining request parameter lists, to indicate 
the next list. 

ACB = address 

specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you used the ACB macro to 
generate the control block, you may specify the label of that macro for the 
address. If the ACB parameter is not coded, you must specify the address 
before issuing the request. 


AM- VSAM 

specifics that the access method using the control block is VSAM. 

AREA = address 

specifies the address of a work area to and from which VSAM moves a data 

record if you request it to do so (with the RPL parameter 

OPTCD = MVE). If your request is to process records in the I/O buffer 
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(OPTCD = LOC), VSAM puts into this work area the address of a data 
record within the I/O buffer. 

AREALEN = number 

specifies the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for OPTCD - MVE is the size of a 
data record (of the largest data record, for a data set with records of variable 
length). For OPTCD = LOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 

ARG = address 

specifies the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG field must be 4 bytes long. For direct or skip-sequential 
processing, this field contains your search argument, a relative record 
number. For sequential processing (OPTCD = (KEY.SEQ)), the 4 bytes 
arc required for VSAM to return the feedback RRN. For keyed access 
(OPTCD = KEY), the search argument is a full or generic key or relative 
record number; for addressed access (OPTCD = ADR), it is an RBA. If 
you specify a generic key (OPTCD = GEN), you must also specify in the 
KEYLEN parameter how many of the bytes of the full key you are using 
for the generic key. ARG is also used with WRTBFR and MRKBFR. Its 
usage with these macros is described in “Sharing Resources” in VSAM 
Administration Guide. 

ECB -address 

specifics the address of an event control block (ECB) that you may supply. 
VSAM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which arc described in Data Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. (If you issue a CHECK before a request is 
complete, you give up control and must wait for completion.) The ECB 
parameter is always optional. 

KEYLEN — number 

specifies the length, in bytes, of the generic key (OPTCD = GEN) you are 
using for a search argument (given in the field addressed by the ARG 
parameter). This parameter is specified as a number from 1 through 255; it 
is required when the search argument is a generic key. For full-key 
searches, VSAM knows the key length, which is taken from the catalog 
definition of the data set when you open the data set. 

MSG AREA = address 

specifies the address of an area that you may, optionally, supply for VSAM 
to send you a message in case of a physical error. The format of a physical 
error message is given in “Reason Code (Physical Errors)” on page 26. 

MSGLEN = number 

specifies the size, in bytes, of the message area indicated in the MSGAREA 
parameter. If MSGAREA is specified, MSGLEN is required. The 
minimum size of a message is 128 bytes; if you provide less than 128 bytes, 
no message is returned to your program. 
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NXTRPL = address 

specifies the address of the next request parameter list in a chain. Omit this 
parameter from the macro that generates the last list in the chain. When 
you issue a request that is defined by a chain of request parameter lists, 
indicate in the request macro the address of the first parameter list in the 
chain. 

OPTCD = (lADRlCNVl KEYl 
I.DIR1SEQISKPI 
URD ILRD1 
I. FWD 1BWDI 
I.ASYI SYNI 
|,NSP|NUP|UPD| 
f,KEQ|KGEl 

i.fksigeni 

I. N W AITX 1WAITX1 
IXOCI MVE1 ) 

specifies the subparameters that govern the request defined by the request 
parameter list. Each group of subparameters has a default; subparameters 
are shown in Figure 13 with defaults underlined. Only one subparameter 
from each group can be specified. Some requests do not require an 
subparameter from all of the groups to be specified. The groups that aren't 
required arc ignored; thus, you can use the same request parameter list for a 
combination of requests (GET, PUT, POINT, for example) without 
zeroing out the inapplicable subparameters each time you go from one 
request to another. 


Meaning 

Addressed access to a key-sequenced or an entry-sequenced 
data set: RBAs are used as search arguments and sequential 
access is done by entry sequence. 

Control interval access (this type of access is described in 
VS AM Administration Guide). 

Keyed access to a key-sequenced or relative record data set: 
keys or relative record numbers are used as search arguments 
and sequential access is done by key or relative record number 
sequence. 

Direct access to a key-sequenced, entry-sequenced, or relative 
record data set. 

Sequential access to a key-sequcnccd, entry-sequenced, or 
relative record data set. 

Skip sequential access to a key-sequcnccd or a relative record 
data set: used with keyed access only. 


Option 

ADR 

CNV 

KEY 

DIR 

SE£> 

SKP 


Figure 13 (Part I of 3). OPTCD Options 
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Option 

ARP 

LRD 

FUl) 

BWD 

ASY 

SYN 

NSP 

NUP 

UPD 

KE2 

Figure 13 


Meaning 

User's argument determines the record to be located, retrieved, 
or stored. 

Last record in the data set is to be located (POINT) or 
retrieved (GET direct); requires OPTCD = BWD. 

Processing to proceed in a forward direction. 

Processing to proceed in a backward direction; for keyed 
(KEY) or addressed (ADR) sequential (SEQ) or direct (DIR) 
requests; valid for POINT, GET, PUT, and ERASE 
operations; establish positioning by a POINT with 
OPTCD = BWD or by a GET direct with 
OPTCD = (NSP,BWD). When OPTCD = BWD is specified, 
subparameters KGE and GEN are ignored; subparameters 
KEQ and FKS arc assumed. 

Asynchronous access; VSAM returns to the processing 
program after scheduling a request so the program can do other 
processing while the request is being carried out. 

Synchronous access; VSAM returns to the processing program 
after completing a request. 

With OPTCD = DIR only, VSAM is to remember its position 
(for subsequent sequential access); that is, the position is not to 
be forgotten unless an ENDREQ macro is issued. 

A data record that is being retrieved will not be updated or 
deleted; & record that is being stored is a new record; VSAM 
doesn't remember its position for direct requests into a work 
area. 

A data record that is being retrieved may be updated or deleted; 
a record that is being stored or deleted was previously retrieved 
with G?TCD= UPD; VSAM remembers its position for 
sequential and direct GET requests. When PUT is issued after 
a DIRUPD GET request, PUT causes VSAM to release 
exclusive control. 

For GET with OPTCD = (KEY,DIR) or (KEY.SKP) and for 
POINT with OPTCD = KEY, the key (full or generic) that you 
provide for a search argument must equal the key or relative 
record number of a record. For a relative record data set, KEQ 
is assumed except for POINT. 


(Part 2 of 3). OPTCD Options 
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Option Meaning 

KGE For the same cases as KEQ, if the key (full or generic) that you 

provide for a search argument doesn't equal that of a record, 
the request applies to the record that has the next higher key. 
For a relative record data set and POINT, KGE positions to 
the specified relative record number whether the slot is empty 
or not. If the relative record number is greater than the highest 
existing record, EOD is returned. A subsequent PUT will 
insert the record at this position. 

FKS A full key is provided as a search argument. 

GEN A generic key is provided as a search argument; give the length 

in the KEYLEN parameter. 

NWAITX Never take the user's UPAD exit. 

WAITX If OPTCD* SYN and the ACB's MACRF = LSR GSR and 
UPAD exit routing is specified, VSAM takes the UPAD exit at 
points when VSAM would normally issue a WAIT. 

LOC I ; or retrieval, VSAM leaves the data record in the I/O buffer 

for processing; not valid for PUT or ERASE; valid for GET 
with OPTCD= UPD. However, to update the record, you 
must build a new version of the record in a work area and 
modify the request parameter list OPTCD from LOC to MVE 
before issuing a PUT. For keyed-sequential retrieval, 
modifying key fields in the I/O buffer may cause incorrect 
results for subsequent GET requests until the I/O record is 
reread. 

MVE For retrieval, VSAM moves the data record to a work area for 

processing, and for storage, VSAM moves it from the work 
area to the I/O buffer. 


Figure 13 (Part 3 of 3). OPTCD Options 
RECLEN = number 

specifies the length, in bytes, of a data record being stored. This parameter 
is required for a PUT request. 

For GET requests, VSAM puts the length of the record retrieved in this 
field in the request parameter list. It will be there if you update and store 
the record. 

TRANSID = number 

specifics a number that relates modified buffers in a buffer pool. Used in 
shared resource applications and described in the chapter “Sharing 
Resources” in VSAM Administration Guide. 
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RPL 


In this example, an RPL macro is used to generate a request parameter list 
named PARM LIST. 

ACCESS ACB MACRF=(SKP,OUT), 

DDNAME=PAYROLL 


PARMLIST 

RPL 

ACB=ACCESS, 
AM=VSAM, 
AREA=WORK, 
AREALEN=125, 
ARG=SEARCH, 
MSGAREA=ME S SAGE 



MSGLEN=128, 
OPTCD=(SKP,UPD) 

WORK 

DS 

CL125 

SEARCH 

DS 

CL8 

MESSAGE 

DS 

CL128 


Most OPTCD defaults are 
appropriate to assumptions. 


The ACB macro named ACCESS, specifics skip-sequential retrieval for update. 

Further details may be provided on a DD statement named PAYROLL. 

The RPL macro's parameters are: 

• ACB associates the request parameter list with the access method control 
block generated by ACCESS. 

• AREA and AREALEN specify a work area, WORK, that is 125 bytes long. 

• ARG specifics that the search argument is defined at SEARCH. 'The search 
argument is 8 bytes long. 

• MSGAREA and MSGLHN specify a message area, MESSAGE, that is 128 
bytes long. The message area is provided for physical error messages. 

• OPTCD specifics skip-sequential processing and specifics that a retrieved 
record may be updated or deleted. 

Because KEYLEN is not coded, a full-key search is assumed. 
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SCHBFR Macro (Search Buffer) 

The format of the SCHBFR macro is: 


SCHBFR 


|BFRNO = number j 
,RPL =* address 


BFRNO = number 

specifies the number of the buffer VSAM is to search first. The buffers 
preceding it in the buffer pool are not searched. The default is 1; that is, 
the first buffer is searched first. (If the number is coded in register notation, 
all registers except 1 and 13 may be used.) 

RPL = address 

specifies the address of the request parameter list that defines the SCIIBFR 
request. These RPL parameters have meaning for SCHBFR: 

ACB = address 


AREA = address 

If a buffer is found, the area whose address is specified will contain its 
address (OPTCD= LOC) or a copy of its contents (OPTCD= MVE). 

AREALEN 3 number 

At least 4 with OPTCD= LOC; at least control interval size with 
OPTCD= MVE. 

ARG = address 

ARG gives the address of an 8-byte field that contains the beginning 
and ending control interval RBAs of the range to be searched on. 

ECB = address 


OPTCD = HASYI SYNU LOCI MVE) ) 


TRANSID = number 


All other RPL parameters are ignored. RPLs are assumed not to be 
chained. Control interval access is assumed. 

If the ACB to which the RPL is related has MACRF = GSR, the program 
that issues SCHBFR must be in supervisor state with protection key 0 to 7. 
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SHOWCB Macro (Display Fields of an Access Method Control Block) 

The format of the SHOWCB macro used to display fields in an access method 
control block is: 


\label\ 


SHOWCB 


ACB = address 
,AREA = address 
,LENGTH = number 
|,OBJECT = PATA 1INDEX1 
,FI ELDS - (|ACBLEN| |,AVSPAC| 
|,BFRFND|[,BSTRNO] 

|,BUFNOJ |,BUFRDS| 

|,BUFSP| 

|,CINV| |,DDNAME||,ENT)RBA| 

|,ERROR) |,EXLST||,FS| 
|,HALCRBA| |,KEYLEN||,LRECL| 
|,MAREA| |,\1LEN||,NCIS| 
|,XDELR| |,NEXCP||,NEXT| 
|,MXL) l,NLOGR)|,NRETR| 
|,NLTW| |,NUPDR||,PASSWD| 
|,SHRPOOL) |,S IMS I )|,S I RiMAX) 
|,STRNOj |,UIW|) 


The parameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-typc address constants. Appendix C, “Operand 
flotation” on page l€i, -further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SHOWCB 
macro. 

ACB = address 

specifies the address of the access method control block whose fields are to 
be displayed. If you used the ACB macro with a label, you can specify the 
label here. The ACB parameter is optional when you wish to display the 
length of an access method control block (FIELDS = ACBLEN). (All 
access method control blocks have the same length, so you need not specify 
the address of a particular one.) 

AREA * address 

specifies the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 

The contents of the fields are displayed in the order in which you specify 
them. The area must begin on a fullword boundary. 

LENGTH = number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. (See the FIELDS parameter for 
the fields that can be displayed and for the length of each field.) If the area 
is not large enough for all the fields, VSAM doesn't display any of their 
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contents and returns a reason code (see “Control Block Manipulation 
Macro Return Codes and Reason Codes” on page 10). 

OBJECT = DATA I INDEX 

specifies whether fields are to be displayed for the data or for the index. 
FIELDS -1 AC BLENJf,A VSP AC| 

|,BFRFND||,BSTRNO| 

|,BCFND||,BIJFNI| 

|,BUFNO||,BUFRDS| 

|,BLFSP||,CINV| 

|,DDNAMEff,ENDRBA| 

|,ERROR||,EXLST| 

|,FSJ|,HALCRBA| 

(,KKYLEX||,LRKCL| 

|,MAREAH,\ILEN| 

|,NCIS||,NDELR| 

|,NEXCT > ||,NEXT| 

1AINSR||,NIXL| 

|,NLOGR||,NRETR| 

| t NSSS||,NUI\\1 

|,NLPDR||,PASSWD| 

(,RKP||,SI!RPOOL| 

|,STMSTj|,STRMAX| 

l,STRNO|!,i;i\\T) 

specifics the fields whose contents are to be displayed. Some of the fields 
can be displayed at any time; others only after a data set is opened. The_ 
ones that ca n be d isplayed o nly after a data set is opened can, in the case of 
a key-sequenced data sefthat has been o pened f or ke yed acc ess, pertain 
citncr to Ike data ui 10 llie inacx. ace the OBJECT parameter. Figure 14 
explains the keywords you can code in the FIELDS parameter for an access 
method control block. 


Keyword Fullwords Description of the Field 

Note: The following fields can be displayed at any 
time. 

ACBLEN I Length of an access method control block 

(displaying the length of an access method control 
block gives your program independence from 
changes in the length that may occur from release 
to release of VSAM) 

BSTRNO 1 Number of strings initially allocated for access to 

the base cluster by a path 

BUFND 1 Number of I/O buffers to be used for data, as 

specified in the ACB (or GENCB) 


Figure 14 (Part 1 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 
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Keyword 

Fullwords 

Description of the Field 

BUFNI 

1 

Number of I/O buffers to be used for index entries, 
as specified in the ACB (or GENCB) 

BUFSP 

1 

Amount of space specified in the ACB (or 

GENCB) for I/O buffers 

DDNAME 

2 

Name of the DD statement that identifies the data 
set 

ERROR 

1 

Ihe code returned by VS AM after the opening or 
closing of the data set (see “OPEN Macro (Connect 
Program and Data)” on page 107 and “CLOSE 
Macro (Disconnect Program and Data)” on 
page 55). 

EXLST 

1 

Address of the exit list, if any; 0 if none 

M AREA 

1 

Address of the message area, if any; 0 if none 

MLEN 

1 

Length of the message area, if any; 0 if none 

PASSWD 

1 

Address of the field containing the password; the 
first byte of the field contains the length of the 
password (in binary) 

SHRPOOL 

1 

Identification number of resource pool to be used 
for LSR processing 

STRMAX 

1 

Maximum number of strings concurrently active 

STRNO 

1 

Number of requests for which VSAM is prepared 
to remember its position in the data set 



Note: 'Hie following fields can be displayed only 
after the data set is opened. 

AVSPAC 

1 

Amount of available space in the data component 
or index component, in bytes 

BFRFND 

1 

Number of successful look-asides 

BUFNO 

1 

Number of I/O buffers actually in use for the data 
component or index component 

BUFRDS 

1 

Number of buffer reads 

CINV 

1 

Control interval size for the data component or 
index component 


Figure 14 (Part 2 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 
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Keyword Fullwords Description of the Field 

END RBA 1 Ending RBA of the space used by the data 

component or index component; not the RBA of 
any record in the data set, but of the last used byte 
in the data set 

FS 1 Number of free control intervals per control area in 

the data component (0 for OBJECT = INDEX) 

HALCRBA 1 High-allocated RBA; the relative byte address of the 

end of the data component (OBJECT = DATA) or 
the index component (OBJECT = INDEX) 

KEYLEN 1 Length of the key of reference of the key field of 

data records in the data component (whether 
OBJECT = DATA or INDEX) 

LRECL 1 Length of data records in the data component 

(maximum length for variable-length data records) 
or of index records in the index component (control 
interval length minus 7) 


NCIS 

1 

Number of control intervals that have been split in 
the data component (0 for OBJECT = INDEX) 

NDELR 

1 

Number of records that have been deleted from the 
data,component (0 for OEJECT 3 INDEX) 

NEXCP 

1 

Number of EXCP macros that VSAM has issued 
for access to the data component or index 
component. 

NEXT 

l 

Number of extents now allocated to the data 
component or index component (the maximum 
that can be allocated in 123) 

NINSR 

1 

Number of records that have been inserted into (or 
added to) the data component (0 for 

OBJECT = INDEX) 

NIXL 

1 

Number of levels in the index component (0 for 
OBJECT = DATA) 

NLOGR 

1 

Number of records in the data component or index 
component 

NRETR 

1 

Number of records that have ever been retrieved 
from the data component (0 for 

OBJECT = INDEX) 

NSSS 

1 

Number of control areas that have been split in the 
data component (0 for OBJECT = INDEX) 


Figure 14 (Part 3 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 


136 MVS/XA VSAM Administration: Macro Instruction Reference 



SHOWCB—ACB 


Keyword 

Full words 

Description of the Field 

NUIW 

1 

Number of writes not initiated by the user 

NUPDR 

1 

Number of records in the data component or index 
component that have ever been updated 

RKP 

1 

Displacement of the key of reference of the key field 
from the beginning of a data record (whether 
OBJECT = DATA or INDEX) 

STMS! 

2 

System time stamp, which gives the time and day of 
the last time the data component or index 
component was closed, with bit 51 (counting from 

0 at the left) equivalent to one microsecond and bits 
52 through 63 unused 

UIW 

1 

Number of user-initiated writes 


Figure 14 (Part 4 or 4). FIELDS Operand Keywords for an Access Method Control 

Block 


Example 1: SHOWCB Macro (Display an Access Method Control Block) 


In this example, a SHOWCB macro is used to display fields in an access method 
control block. The fields displayed (KEYLEN, LRECL, and RKP) permit the 
program to modify variables to process any one of a number of data sets that 
have different sized key fields and records and different placements of key field in 
a record. 


SHOWCB ACB=CONTROL, 
AREA=DISPLAY, 
FIELDS=(KEYLEN, 
LRECL,RKP), 
LENGTH=12 

DISPLAY DS OF 

KEYLEN DS F 

LRECL DS F 

RKP DS F 


Align on fullword boundary. 


The SHOWCB macro's parameters arc: 

• ACB specifics the address of the access method control block to be displayed. 

• AREA specifics that the area to be used to display access method control 
block fields is to begin on a fullword boundary. 

• FIELDS specifies that the KEYLEN, LRECL, and RKP fields are to be 
displayed. 

• LENGTH specifies that the length of the area to be used for the display is 12 
bytes, enough to accommodate the specified fields. 
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This display enables the program to set up its variables for the particular data set 
it has opened. 

Example 2: SHOVVCB Macro (Display an Exit List Address) 

In this example, a SIIOWCB macro is used to get the address of an exit list by 
displaying the address in an access method control block that uses the exit list. 

SHOWCB ACB=address, 

AREA=address, 

FIELDS=EXLST, 

LENGTH=4 

The SIIOWCB macro's parameters are: 

• ACB specifies the address of an access method control block from which the 
address of an exit list is to be displayed. 

• AREA and LENGTH specify an area and length, 4 bytes, to be used to 
display the address of the exit list. 

• FIELDS specifies that the EXLST field in an access method control block is 
to be displayed. 
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SHOVVCB Macro (Display Fields of an Exit List) 

The format of the SHOWCB macro used to display fields in an exit list is: 


[label\ 

SHOWCB 

EXLST = address 
,AREA -address 
,LENGTH = number 

,FIELDS = (|EODAD| |,E.XLLEN| |,JRNAD| 



|,LERAD||,SYNAD|) 


The subparameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SHOWCB 
macro. 

EXLST = address 

specifics the address of the exit list whose fields are to be displayed. If you 
used the EXLST macro with a label, you can specify the label here. The 
EXLST parameter is optional only when you want to display the length 
that an exit list can have (see FIELDS = EXLLEN below). Ific SHOWCB 
macro does not support the UPAD user exit. 

AREA = address 

specifies ihe address of a work area that you arc supplying for VS AM to 
display the contents of the fields you specify in the FIELDS parameter. 

The contents of the fields arc displayed in the order you specify them. The 
area must begin on a fullword boundary. 

LENGTH = number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. Each exit-list field requires a 
fullword. If the area is not large enough for all the fields, VSAM doesn't 
display any of their contents and returns an error code (see “Control Block 
Manipulation Macro Return Codes and Reason Codes” on page 10). 

FIELDS = (|EOD AI)1|,EXLLEN || ,JRNAD| 

|,LERAI)||,SYNAI)|) 

specifics the values to be displayed, as follows: 

EODAD 

specifies that the address of the end-of-data-set routine is to be 
displayed. 

EXLLEN 

specifies that the length of the exit list indicated in the EXLST 
parameter or if EXLST is omitted, the maximum length an exit 
length can have, is to be displayed. 
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JRNAD 

specifies that the address of the journalizing routine is to be displayed. 

LERAD 

specifies that the address of the logical error analysis routine is to be 
displayed. 

SYNAD 

specifies that the address of the physical error analysis routine is to be 
displayed. 

You can use SHOWCB to display the address of an exit routine only if the exit 
routine is indicated in the exit list. If it isn't, the SHOWCB request will fail. Use 
TESTCB to test whether an entry for a given exit type is present in the exit list 
and to find out whether the exit is active and whether the routine is to be loaded. 

Example: SHOWCB Macro (Display the Length of an Exit List) 

In this example, a SHOWCB macro is used to display the maximum length of an 
exit list. The maximum length of an exit list is subsequently used in a GENCB 


macro to get virtual storage for an exit list. 

SHOWCB AREA=LENGTH, 

FIELDS=EXLLEN, 
LENGTH=4 


L 

GETMAIN 

0,LENGTH 

R,LV=(0) 

Amount of storage for 
GETMAIN. 

LR 

2,1 

Address of storage for 
GENCB. 

GENCB 

BLK=EXLST, 

LENGTH=(*> 

LENGTH), 

WAREA=(2) 

Indirect notation for 
length of work area. 

LENGTH DS 

F 

Contains the length of 
GENCB’s work area. 


The SHOWCB macro's parameters are: 

• AREA and LENGTH specify the area, which begins on a fullword 
boundary, and its length, four bytes, that is to be used for the display. 

• FIELDS specifies that the maximum length of an exit list is to be displayed. 
Because only EXLLEN is specified, the EXLST parameter is omitted. 

The GENCB macro specifies a work area in which an exit list is to be generated. 
The length of the work area is located at LENGTH, where the maximum length 
of an exit list was put as a result of the SHOWCB macro. 
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SHOWCB Macro (Display Fields of a Request Parameter List) 


The format of the SHOWCB macro used to display fields in a request parameter 
list is: 


\label\ 

SHOWCB 

RPL = address 
, A R E A = address 
, LENGTH = number 

.FIELDS = (| ACB||,AIXPCJ|,AREA||,AREALEN| 



|,ARG||,KCB||,FI)BK||,tTNCD| 

|,KEYLEN|[,MSGAREA| 

|,MSGLEN| 

|,NXTRPL||,RBA| 

|,RECLEN| 

I.RPLLENJ 

I.TRANSIDJ) 


The parameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SHOWCB 
macro. 

R1*L = address 

specifies the address of the request parameter list whose fields arc to be 
displayed. If you used the RPL macro with a label, you can specify the 
label here. The RPL parameter is optional when you want to display the 
length of a request parameter list (FIELDS = RPLLEN). (All VSAM 
request parameter lists have the same length, so you need not specify the 
address of a particular one.) 

AREA =.address 

specifics the address of a work area that you arc supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 

The contents of the fields arc displayed in the order you specify them. The 
area must begin on a full word boundary. 

LENGTH = number 

specifies the length, in bytes, of the work area that you arc providing for 
VSAM to display the indicated fields in. Each request parameter list field 
requires a fullword. If the area is not large enough for all the fields, VSAM 
doesn't display any of their contents and returns an error code (see 
“Control Block Manipulation Macro Return Codes and Reason Codes” on 
page 10). 
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HELDS = (|ACB||,AIXPC||,AREA||,AREALEN|[^ARG| 
(,ECB||,FDBK|f,FTXCD|(,KEYLEN| 

|,MSGAREAJ(,MSGLEN| 

|,NXTRPLH,RBA||,RECLEN| 

I,RPLLEN||,TRANSID|) 

specifics the fields whose contents are to be displayed. Figure 15 on 
page 142 explains the keywords you can code in the FIELDS parameter for 
a request parameter list. Some fields (each indicated by an asterisk (*) in 
Figure 15) are meaningful only if the requests have been completed; 
therefore, you must wait until the request has completed (for example, by 
issuing a CHECK if the request is asynchronous) before issuing SHOWCB. 


Keyword Fullwords Description of the Field 

ACB 1 Address of the access method control block that 

relates the request parameter list to the data 

AIXPC* 1 Number of alternate index pointers 

AREA 1 Address of the work area that the program uses to 

process a data record for the access as defined by 
the request parameter list 

AREALEN 1 Length of the work area whose address is given in 

AREA 

ARC 1 Address of the field containing a search argument, 

if search arguments are being used 

ECB* 1 Address of an event control block, if any, in which 

VSAM indicates the completion of requests 
defined by the request parameter list 

FDBK* 1 Reason code that VSAM puts into the feedback 

field to describe the error detected for the 
preceding request. (The meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logical or physical error. See 
“Record Management Return Codes and Reason 
Codes” on page 13) 

FTNCD* 1 Code that describes the function in which a logical 

or physical error occurred; indicates whether the 
upgrade set may have been modified incorrectly by 
the preceding request ('Hie meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logical or physical error. See 
“Record Management Return Codes and Reason 
Codes” on page 13) 


Figure 15 (Part I of 2). FIELDS Operand Keywords for a Display Request Parameter 

List 
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Keyword Fullwords Description of the Field 

KEYLEN 1 

Length of the search argument, if a generic key is 
used for a search argument 

MSGAREA* 1 

Address of the area, if any, into which VS AM puts 
physical error messages 

MSGLEN 1 

Length of the message area, if any 

NXTRPL 1 

Address of the next request parameter list, if 
another one is chained to this one 

RBA* 1 

Relative byte address of the most recently 
processed record; you could use it to record the 
RBAs of records that you are retrieving or storing 
sequentially or by key 

RECLEN* 1 

Length of the data record, access to which is 
defined by the request parameter list 

RPLLEN 1 

Length of a request parameter list 

TRANSID 1 

Number that relates modified buffers in a buffer 
pool; described in VS AM Administration Guide 


Figure 15 (Part 2 of 2). FIELDS Operand Keywords for a Display Request Parameter 

List 


/ 
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Example: SHOWCB Macro (Display a Physical Error Message) 

In this example, a SHOWCB macro is used to display a physical error message. 
This example assumes that there is no SYNAD routine (or the SYNAD exit is 
inactive), in which case, VSAM returns control to your program following the 
last executable instruction if a physical error occurs. Register 15 indicates a 
physical error (12), and the feedback field in the request parameter list contains a 
code identifying the error; the message area contains more details about the error. 
Register 1 points to the request parameter list. 

REQUEST RPL MSGAREA= 

MESSAGES, 

MSGLEN=128 


SHOWCB AREA=MSGADDR, 

FIELDS=MSGAREA, 
LENGTH=4, 

RPL=REQUEST 

LTR 15,15 

BNZ CHECKO 


CHECKO 


Display failed. 


MESSAGES DS CL128 For VSAM to give you a 

detailed message about 
a physical error. 

MSGADDR DS F For displaying the 

address of the message 
area with SHOWCB. 

The RPL macro in this example provides for a message area, MESSAGES, of 

128 bytes to be used for any physical error message. 

The SHOWCB macro's parameters are: 

• AREA and LENGTH specify a 4-byte area, MSGADDR, to be used for 
displaying the address of the message area for the associated request 
parameter list. 

• FIELDS specifies that the address of the message area is to be displayed. 

• RPL specifics the name, REQUEST, of the request parameter list for which 
the message area address is to be displayed. 
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TESTCB Macro (Test Fields of an Access Method Control Block) 


Only one keyword can be specified each time you issue TESTCB. The format of 
the TESTCB macro used to test a field in an access method control block is: 



TESTCB ACB = address 

|,ERET = address] 

I,OBJECT = DATA | INDEX! 

,{ATRB = (|ESDS||,KSDS|(,LDSJ| ,R EPL) 
|,RRDS||,SPAN||,SS\VD||,\VCK|| 

ATRB = UNQ| 

CATALOG ■ YES|NO| 

CRA m SCRA|UCRA| 

MACRF = (|ADR||,AIX||,CFX||,CNV||,DDN| 
|,DFR||,DIRH,DSN|I,GSR||,ICI||,IN| 
|,KEY||,LSR||,NCI||,NFDH,NFX||,MS1 
[,NRM||NRS||,NSR||,NUB|[,OUT||,RST 
!,SEQ||,SIS||,SKI>||,UBF|)| 

OFLAGS = OPEN | 

OPENOBJ = PATH | BASE) AIX | 

ACBLEN = number \ 

AVSPAC = number\ 

BSTRNO = number\ 

BLEND = number\ 

BUFNI = number\ 

BUFNO = number\ 

BUFSP = number\ 

CINV = number\ 

J>D\ AME^= <idname\ 

ENDRBA = number] 

ERROR = number | 

EXLST= address\ 

FS = number\ 

KEYLEN = number\ 

LRECL = number\ 

MARE A = address\ 

MLEN = number\ 

NCIS = number] 

NDELR = number] 

NEXCP - number] 

NEXT “ number] 

NINSR = number] 

NIXL * number] 

NLOGR = number] 

NRE'I'R = number] 

NSSS = number] 

NUPDR = number] 

PASSWD = address] 

RKP = number] 

SHRPOOL = number] 

STM ST = address] 

STRNO = number) 
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The subparameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

ACB = address 

specifies the address of the access method control block whose information 
you want to test. You may omit it only if you're testing the length of an 
access method control block (ACBLEN = number). (All VSAM access 
method control blocks have the same length.) 

ERET = address 

specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register 0 the reason it couldn't. 
('ITie reasons are discussed under “Control Block Manipulation Macro 
Return Codes and Reason Codes” on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

OBJECT = DATA I INDEX} 

specifies whether you want to test a field for data or for index. 

ATRB = (|ESDS||,KSDS|[,LDS| 

I,REEL! 

|,RRDS| 

I,SPAN} 

1,SS\VD| 

1,\VCK|) 

specifies, for an open data set, the attribute that is to be tested for, as 
follows: 

ESI)S 

entry-sequenced data set 
KSDS 

key-sequenced data set 

LDS 

linear data set 

Note: When specified, LDS must be the only parameter indicated by 
ATRB. All other parameters will be ignored and a binary test will be 
performed that indicates whether the data set is a linear data set 
(return code 0) or not (return code 1). 
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REPL 

some portion of the index is replicated 

RRDS 

relative record data set 
SPAN 

data set contains spanned records 
SSWD 

sequence set is adjacent to the data 

WCK 

write operations for the data set are being verified 


ATRB-UNQ 

specifics, for an open alternate index or path, that the alternate index 
requires unique keys. The test for ATRB = UNQ must be made with a 
separate TESTCB macro. VSAM examines the path control blocks for the 
UNQ attribute; and also examines the base cluster's control blocks for the 
other attributes. If other attributes arc tested for, VSAM examines the base 
cluster's control blocks for all attributes: The test for ATRB= UNQ would 
give inaccurate results when applied to the base cluster's control blocks. 

CATALOG-YESINO 

specifics that a test is to be made to determine, any time, whether or not 
the access method control block specifics a catalog data set. 

CRA = SCRA|UCRA 

specifies that a test is to be made to determine, any time, whether catalog 
recovery area control blocks are to be built in system storage or user 
storage. 

MACRF - (|ADR|I,AIX|1,CFX| 

|,CNVH,I>DNJ 

|,DFR||,DIR| 

|,DSX|,GSR| 

|,IC1H,IN| 

|,KEY|,LSR| 

|,NCI||,M>F| 

|,NFX||,NIS| 

|,NRM|j,NRS| 

|,NSR||,NUB1 

|,OUT||,RSF| 

|,SEQH,SIS| 

|,SKP||,UBF| 

specifies that a test is to be made to determine, at any time, what 
subparameter or combination of subparameters is being used for processing. 

OFLAGS * OPEN 

specifies that a test is to be made to determine, after open, whether the data 
set identified by the control block has been opened. 
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OPENOBJ = PATH|BASEJ AIX 

specifies that a test is to be made to determine, after open, whether an 
opened object is a path, a base cluster, or an alternate index. 

The remaining parameters represent fields in an access method control block that 
can be compared with the value specified. These fields are the same as those that 
can be displayed by using the SIIOWCB macro and are described in Figure 14 
on page 134. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 

Example: TESTCB Macro (Test for Data Set Attributes) 

In this example, a TESTCB macro is used to determine whether a data set is a 
key sequenced or an entry-sequenced data set. 

LIST RPL 


SHOWCB AREA=DATAFACT, 
FIELDS=ACB, 
LENGTH=4, 
RPL=LIST 


LTR 

BNZ 


15*15 

CHECKO 


TESTCB ACB=(*, 

DATAFACT), 
ATRB=KSDS, 
ERET=CHECKO 


BE 


KEYSEQ 


KEYSEQ 

CHECKO 


DATAFACT DS 


Is the data set key 
sequenced? 


Yes. 

Data set is key sequenced. 
Display or test failed. 


For displaying address of 
access method control 
block. 


The SHOWCB macro's parameters are: 

• AREA and LENGTH specify a 4-byte area, DATAFACT, aligned on a 
fullword boundary, to be used for the display. 

• FIELDS and RPL specify that the address of the access method control 
block in the LIST request parameter list is to be displayed. 

The TESTCB macro's parameters are: 
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• ACB specifics that a field in the access method control block, the address of 
which is located at DATAFACT, is to be tested. The SHOWCB macro put 
the address of the access method control block at DATAFACT. 

• ATRB specifics that the access method control block is to be tested to 
determine whether it is a key-sequenced data set. 

• FRET specifies that a routine named C1IECK0 is to be given control if an 
error occurs that makes it impossible to make the test. 

There is no need to examine the feedback field in an EODAD routine, because it 

can be assumed to contain the end-of-data-set indication. 
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TESTCB Macro (Test Fields of an Exit List) 

The format of the TESTCB macro used to test fields in an exit list is: 

\label[ TESTCB I EXLST - address 
|,ERET = address] 

,{EODAD = {0|(Iaddre.w||,A|N||,LD} I 
JRNAD = {0|((a</drerr||,A|N||,LJ)}! 

LERAD* {0|(|addrejj||,A|NH,E|))l 
SYNAD* {0|(|uddrer4,A|N|l,L|)]} 

|,EXLLEN = number] 

The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the TESTCB macro. 
EXLST - address 

specifies the address of the exit list whose information you want to test. 

You may omit it only if you're testing the maximum length of an exit list 
(EX LLEN=number). The TESTCB macro does not support the UPAB 
user exit. 

ERET = address 

specifics the address of a routine to which VS AM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register 0 the reason it couldn't. 
(The reasons are discussed under “Control Block Manipulation Macro 
Return Codes and Reason Codes” on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

EODAD » {0|(|add!rerr||,A|N|I,L|)} | 

JRNAD = {0|(|arfc/rerj||,A|N||,L|)) | 

LERAD = [01 (\addressl \,\| N j(,LJ)} 1 
SYNAD = {0|(|a^/rejr||,A|NI|,L|)} 

specifies the exit about which you arc asking a yes-no question. If you 
code more than one parameter for an exit name, each must equal the 
corresponding value in the control block for you to get an equal condition. 
The values that can be tested are: 

0 

specifies that a test is to be made to determine whether an entry is 
provided for the exit in the exit list. 
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address 

specifies that a test is to be made to determine whether this is the 
address of the exit. Tests for an address result in an equal, unequal, 
high, low, not-high, or not-low condition. Tests for a combination of 
an address and A, N, or L result in an equal or unequal condition. 


A|N 

specifies that a test is to be made to determine whether an exit is 
active (A) or not active (N). Tests for A or N result in an equal or 
unequal condition. 

L 

specifies that a test is to be made to determine whether the address is 
the location of an 8-byte field containing the name of a module to be 
loaded rather than the entry point of the routine. Tests for L result in 
either an equal or unequal condition. 

EXLLEN = number 

specifies cither the maximum length that an exit list can have (if you don't 
code the liXI^ST parameter) or the actual length of the exit list indicated by 
the EXIiiT parameter. If you specify an exit, you may not also specify 
EXLLEN; if you specify EXLLEN, you may not also specify an exit. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 

Example: TESTCB Macro (Use a Branch 'Fable) 

In this example, a TESTCB macro is used to test whether ENDPROC is the 
routine supplied for the EODAD exit in the exit list EXITS, and whether the 
EODAD exit is active. A branch table is used to determine whether the test is 
successful. 


TESTCB EODAD=(ENDPROC,A) Is ENDPROC supplied and is 
EXLST=EXITS the exit active? 

B *+4(15) 


If the test was made successfully, register 15 contains 0 and the next instruction is 
executed. 


B TEST1 

If it was unsuccessful, register 15 contains 4 and the next instruction is executed. 

ABEND 2,DUMP 
TEST1 BNE NO 

YES ... Yes; ENDPROC is supplied 

and active. 

NO ... ENDPROC isn't supplied, or 

the exit isn't active. 
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TESTCB Macro (Test a Request Parameter List) 

The format of the TESTCB macro to test fields in a request parameter list is: 


[label\ 

TESTCB 

RPL = address 
|,ERET = address\ 

,{AIXFLAG =» AIXPKP| 

AIXPC = number\ 

FTNCD = number\ 

IO = COMPLETE | 

OPTCD = (|ADR||,ARD|!,ASY1(,BWD| 



|,CNV||,DIR||,EKS||,FWD| 

|,GEN||,KEQ1[,KEY||,KGE||,LOC| 
|,LRI)||,MVE||,NSP||,NLP||,SEQ| 
|,SKPJ|,SYN|l,UPD|)| 



ACB = address] 

AREA = address | 

AREALEN = number | 

ARG = address | 

ECB = address] 

FDBK =* number | 

KEYLEN = number] 

MSGAREA = address | 

MSGLEN = number | 



NXTRPL = addressi 

RBA = number | 

RECLEN = number | 

RPLLEN = number\ 

TRANSID — number) 


The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, “Operand 
Notation” on page 181, further defines these operand expressions. 

where: 

label 

is 1 to 8 characters that provide a symbolic address for the TESTCB macro. 
RPL = address 

specifies the address of the request parameter list whose information you 
want to test. You may omit it only if you're testing the length of a request 
parameter list (RPLLEN = number). (All request parameter lists have the 
same length.) 

ERET = address 

specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
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TESTCB—RPL 


could do the test and, if not, indicates in register 0 the reason it couldn't. 
(The reasons are discussed under “Control Block Manipulation Macro 
Return Codes and Reason Codes” on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an abend. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

AIXFLAG = AIXPKP 

specifics that prime-key pointers are used rather than RBAs. 

AIXPC = number 

specifics the pointer count. 

FTNC1) = number 

specifies whether the upgrade set is correct or may have been modified by a 
request. These codes are described under “Component Codes 
(RPLCMPON)” on page 14. 

IO = COMPLETE 

specifics that a test is to be made to determine whether an asynchronous 
request has been completed. (When you issue a CHECK macro, you 
suspend processing until a request has been completed if it hasn't yet been 
completed.) 

OPTCD = (|,ADR||,ARD||,ASY||,BWD||,CNV||,DIR|1,FKS| 

I. FWl)|| f GENU, KEQH,KEY||,KGE||, LOCH, LRD] 

| ,M V E|| ,N SP|| ,N L’ P || ,SEQ|1 ,SK P|| ,S YN || ,U PI) | 
specifics that a test is to be made to determine what subparameter or 
combination of subparameters is being used for the request. See Figure 17 
on page 184 for a description of these subparameters. 

1 he remaining parameters specify fields m a request parameter list and values; the 
contents of a field are to be compared to the specified value. These fields are the 
same as those that can be displayed by using a SIIOWCB macro. (See Figure 15 
on page 142 for an explanation of these fields.) Fields can be tested at the same 
time they are displayed. 

You may specify only one keyword. If you code a list of option codes (for 
example, OPTCD = (KEY,DIR)), each of them must equal the corresponding 
value in the control block for you to get an equal condition. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 
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TESTCB—RPL 


Example: TESTCB Macro (Test a Request Parameter List) 

TESTCB RPL=(3), 
RECLEN=80 

BE N0CHN6E 


CHANGE ... Because the record length in 

the request parameter list was 
not 80, the length indicator 
must be modified so that it 
is 80. 

NOCHNGE ... Because the record length in 

the request parameter list was 
80, no change is required. 


The TESTCB macro's parameters arc: 

• RPL specifics that the address of the request parameter list to be tested is 
contained in register 3. 

• RECLEN specifics that the record length indicated in the request parameter 
list is to be tested to determine whether it is 80. 
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VERIFY 


VERIFY Macro (Synchronize End of Data) 

The format of the VERIFY macro is: 


\label\ 

VERIFY 

RPL * address 



I,ACTION * REFRESIi| 


where: 

label 

is 1 to 8 characters that provide a symbolic address for the VERIFY macro. 
RPL •‘address 

specifies the address of the request parameter list that defines this VERIFY 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-typc address constant. 

The following parameter and subparameter arc required for VERIFY: 

In the RPL, OPTCD = (CNV,...) must be specified. 

ACTION « REFRESH 

specifics that the VSAM control blocks arc to be updated from the catalog 
after an attempt has been made to verify the high-used RBA. For a data 
set that has been extended, VERIFY with AC TION = REFRESH will 
invoke end of volume processing to update the control block structure, 
reflecting the new extents. 

If you do not specify ACTION = REFRESH for an extended data set, you must 
close the data set and reopen it to obtain new extent information before you can 
verify it. 

Any attempt to issue the VERIFY macro against a linear data set (EDS) will 
result in a logical error (return code 253 in the feedback field of the RPL). 

After verifying a data set, positioning must be established with a POINT macro 
or with a GET macro with RPL OPTCD = DIR. 
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WRTBFR 


VVRTBFR Macro (Write Buffer) 

The format of the WRTBFR macro is: 


WRTBFR 

RPL = address 


,TYPE= {ALL|CHK|DRBA|DS|LRU(/?erce/iO|TRN} 


RPL = address 

specifies the address of the request parameter list that defines the WRTBFR 
request. An RPL need not be built especially for the 
WRTBFR—WRTBFR may use an inactive RPL that defines other 
request(s) (GET, PUT, and so forth) for a data set that is using the 
resource pool. The following RPL parameters have meaning for 
WRTBFR: 

ACB =* address 
ARG = address 

For TYPE = DRBA, the address of a 4-byte field that contains the 
RBA to be located and written. 

ECU - address 

OPTCD= fASYI SYN) 

WRTBFR can be issued synchronously (SYN) or asynchronously 
(ASY). A CIIECX or ENDREQ must be issued to synchronize an 
asynchronous WRTBFR request. 

TRANSID - number 

Specifies a number from 0 to 31. 

All other RPL parameters are ignored. RPLs are assumed not to be 
chained. 

If the ACB to which the RPL is related has MACRF = GSR, the program 
that issues WRTBFR must be in supervisor state with protection key 0 to 
7. 

TYPE= {ALL|CIlK|l)RBAlDS|LRU(perce«/)|TRN) 
specifies which buffers are to be written. 

Note: Before using WRTBFR TYPE = C1IK|DRBA|TRN, be sure to 
release all buffers. VSAM defers processing until all buffers are released. 

For details about releasing buffers, see VSAM Administration. 

ALL 

specifies that all modified unwritten index and data buffers in each 
buffer pool in the resource pool are to be written. No buffers will be 
invalidated. Closing all the data sets that use a resource pool causes 
the same buffers to be written. 
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WRTBFR 


CHK 

is as TRN (below), but, if an error occurs in writing buffers, 
transaction IDs continue to be associated with the buffers. 

WRTBFR TYPE = CHK could be used by a checkpoint routine to 
record checkpoint information and leave buffers for which an error 
occurred as they were for continued processing. 

DRBA 

specifies that one of the data set's data buffers is to be written. The 
buffer to be written is identified with the RBA pointed to by the RPL 
ARG address. 


DS 

specifics that, for the data set defined by the ACB to which the 
WRTBFR's RPL is related, all modified unwritten index and data 
buffers are to be written and all buffers are to be marked empty, i.e., 
invalidated. Therefore, WRTBFR TYPE = DS should be issued only 
after all VSAM requests for the data set have been quiesced. 
Otherwise, unpredictable results may occur. 

LR \}{pcrcent) 

specifics that some of the modified buffers in each buffer pool in the 
resource pool are to be written. The percent is the percentage of 
buffers in each pool that are to be examined for possible writing. The 
least recently used buffers arc examined. (If percent is coded in 
register notation, only registers 1 and 13 may not be used.) 

TYPE= LRU is used for writing some modified buffers, without 
respect to & particular data set or transaction ID, to ensure that 
buffers will be available for GET requests (without having to wait for 
buffers to be written). 


TRN 

specifies that all buffers in a buffer pool that have been modified by 
requests with the transaction ID specified in the WRTBFR's RPL are 
to be written. Transaction IDs are no longer associated with these 
buffers if WRTBFR completes successfully. 
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Appendix A. Format of Macros 


For easy reference, the formats of all the macros described in this book are 
repeated here in alphabetic order. 

ACB (Generate an Access Method Control Block at Assembly lime) 


]label\ 


ACB 


1AM = VSAMI 
j,BSTRNO = number] 

|,BLFND - number] 

|,BUFNI * number] 

|,BlJFSl» = n«m6e/i 

|,CATALOG - fVESINOIl 

|,CRA={SCRA|UCRA}| 

|,I)DNAME * ddname\ 

|,EXLST = address] 

|,MACRF - nAPRII.CNVH. KEYI 
I.CFXI NFX1 
I.DDMPSN1 
I.DI R I NI)FI 
!,DIR|I,SKQ|[,SKP| 

|,ICI|NCI| 

|,IN|[,OUTi 

I.MSIS1SI 

I. NRM IA1XI 

l.NRSIRSTI 

i.NSRILSRIGSRI 

|,NUB|UBF|)| 

MARE A = address] 

\MLEN = number] 

|,PASS\VD “ address] 

|,RMODE31 - (ALLIBUFFICBI NONKI I 
|,SIIRPOOL*= [^number]] 
j,STRNO « number] 


ACQRANGE (Stage Data) 


| label] 


ACQRANGE 


RPL * address 
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BLDVRP (Build a VS AM Resource Pool) 


BLDVRP 

BUFFERS = ( size{number)jize{number ),...) 


I, FIX = [BFR|IOB|(BFR,IOB)}| 


|,KEYLEN = length] 


LRMODE31 * (ALL|BUFF|CBINO\E)| 


[,SHRPOOL* {0\number}\ 


I,MODE* {24|37}| 


,STRNO * number 


LTYPE* fLSRLDATAUNDEXlIGSRll 


CHECK (Suspend Processing) 


[label | 


CHECK 


RPL * address 


CLOSE (Disconnect Program and Data) 


[ label\ 

CLOSE 

(address\,(options)\...\ 



I,MODE* {24)31 }| 



I,TYPE * T| 


CNVTAD (Convert Address) 


\label\ 


CNVTAD 


RPL = address 


DLVRP (Delete VSAM Resource Pool) 


DLVRP 


TYPE 88 fLSRiGSRI 
|,MODE* {24|3I}| 
|,SHRPOOL* { 9\number}\ 


ENDREQ (Terminate a Request) 


\label\ 


ENDREQ 


RPL * address 


ERASE (Delete a Record) 


\label[ 


ERASE 


RPL 88 address 
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EXLST (Generate an Exit List at Assembly Time) 


\label[ 


EXLST 


IAM = VSAMI 

(,EODAD - (address], \\ N|(,L|)] 
|,IOPID — (address)] 

I4RNAD = (a^r«4A|N||,L|)| 
j,LERAD = (acWre5j|,A|N||,L|)l 
|,SVNAD = (address] , A | NJ[ ,L|)J 
|,UPAD = (address] , A | N|| ,L|» 


GENCB (Generate an Access Method Control Block at Execution Time) 


| label] 


GENCB 


BLK « ACB 
I.AM- VSAMI 
|,BSTRNO - number] 
j,BUFND — number] 

|,BLTNI — number] 

|,BUFSP = number] 

|,CATALOG - {YES|NO)| 
j,COPIES — number] 

|,CRA- {SCRA|UCRA}| 

LDDNAME = ddname] 

|,EXLST - address] 

[,LENGTH = number] 

|,LOC - ( BELOW I ANY) I 
|,MACRF - (IAPRILCNVIL KEYI 
LCFXI NFXI 
|,ODN|l>SNi 
LPFR1NPFI 
|,I)IR||,SE<2J|,SKP| 
i.iciiNcn 
\,TS}[,OUT] 

LNISISISI 

L NRM IAIXI 

|,NRS|RST| 

|,NSR|LSR| 

I.NLB1LBFDI 
|,MAREA = address] 
j,MLEN — number] 
j,PASSWD — address] 

|,RMODE31 - (ALLIBUFFiCBI NONE) l 
f,SHRPOOL«= {^number}] 

|,STRNO = address] 

|,WAREA — address] 
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GENCB (Generate an Exit List at Execution Time) 


[label] 

GENCB 

BLK * EXLST 



I.AM 33 VSAMI 
|, COPIES =* number] 

|,EODAD = (address], A | N|(,L|)| 

IJRNAD = (a^rexjf,A|N||,LI)l 
j,LENGTH 3 number\ 

(,LERAD - (a^rerjf,A|N||,L|)| 

IXOC = fBELOVVIANY) 

|,SYNAD - (a<tarexr|,A|N|I,L|)| 

|,WAREA 83 address] 


GENCB (Generate a Request Parameter List at Execution lime) 


GET (Retrieve a Record) 


[label] 

GENCB 

BLK = RPL 
(,ACB = address] 

I.AM 38 VSAMI 
(, A REA = address] 
j,AREALEN = number] 

1,ARG = address] 

|,COPIES = number] 

(,ECB = address] 

[,KEYLEN = number] 
r f,LENGTHT= number] 

LLOC- fBELOWIANY)! 

|,MSGARE A = address] 

[,MSGLEN = number] 

|,NXTRPL = address] 

|,OPTCD =* (IAI)R|CNV|KEY| 

I.DIRISKQISKPI 

(,ARD|LRD| 

|,FWD|BWD| 

[,ASY|SYN| 

[,NSP|NUP|UPD| 

IXEOIKGEl 

[,FKS|GEN| 

l,LOC|MVE|)| 

|,RECLEN 3 number] 
j,TRANSID 3 number] 
j,WAREA 3 address] 


| label] 

GET 

RPL =* address 
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GETIX (Retrieve an Index Record) 


\label[ 


GETIX 


RPL = address 


MNTACQ (Mount Acquire) 


\label\ 


MNTACQ 


RPL = address 


MODCB (Modify an Access Method Control Block) 


\label\ 


MODCB 


ACB = address 
l,BSTRNO = number] 

[,BLEND = number] 

|,BUFNI = number] 

|,BUFSP = nw/wM 

|,CATALOG = (YES|NO}| 

1,CRA={SCRA|UCRA}| 

(,DD\AME= ddname] 

|,EXLST — address] 

|,M ACRF = (|ADR|I,CNV||,KEY| 
|,CFX|NFX| 

|,DDN|DSN| 

|,DFR|NDF| 

|,DIR||,SEQ||,SKP| 

|,1CI|NCI1 

t,fNH,OLT| 

|,MS|SIS| 

|,NRM|AIX| 

|,NRS|RSTJ 

(,NSR|LSR) 

|,NUB|UBF|)I 
[,M AREA = address] 

|,MLEN = number] 

|,PASSVVD = address J 

|,RMODE3l = f ALL|BUFF|CB|NONE}| 

|,SI IRPOOL - number] 

|,STRNO = number] 


MODCB (Modify an Exit List) 


[i label] 

MODCB 

EXLST = address 



|,EODAD = {address\,\ \ N|I,L|)| 

|,.JRNAD - (a^r«.i,AlN||,LJ)J 
|,LERAD = (a^rejj|,A|N||,LI)| 
l,SYNAD = (a<Wrejj|jA|N||,L|)J 
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MODCB (Modify a Request Parameter List) 


| /obeli 


MODCB 


RPL -address 
f,ACB = address] 
j, AREA = address] 
f,AREALEN = number] 

(,ARG = address ) 
j,ECB * address\ 

|,KEYLEN = number] 
j,MSGAREA = address | 
I.MSGLEN — number] 
|,NXTRPL = address] 

|,OPTCD = (|ADR|CNV|KEY| 
(,ARD|LRD| 
|,FVVD|B\VD| 
[,DIR|SEQ|SKP| 
I,ASY|SYN| 
|,NSP|NUP|UPD| 
f,KEQ|KGE| 
|,FKS|GEN| 
|,LOC|MVE|) 
|,RECLEN — number] 

|,TR ANSID = number] 


MRKBFR (Write Buffer) 


MRKBFR 


MARK* {DINVALID|XINVALID|OUT|RLS} 
,RPL = address 


OPEN (Connect Program and Data) 


[label] 

OPEN 

{address],{options)]...) 



I,MODE* {24|3!)| 


POINT (Position for Access) 


[label] 

POINT 

RPL = address 

PUT (Store a Record) 





[label] 

PUT 

RPL = address 
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PUTIX (Store an Index Record) 



RPL (Generate a Request Parameter List at Assembly Time) 


\label\ RPL ACB = address 

|, AM = VSAM) 

{,AREA = address | 

|,AREALEN = number] 

|,ARG = address | 
f ,ECB = address\ 

|,KEYLEN = number] 

|,MSG AREA = address ) 
|,MSGLEN = number] 
|,NXTRPL * address) 

|,OPTCD = (IADR1CNV1 KEYI 
UMRISEQISKPI 
L ARD ILRDI 
|,ryVD|BWI)| 
I.ASY1 SYN1 
i,NSPI NUP |UPD| 
LKEQIKGEI 
LFKSIGENI 
LNWA1TX 1WAITXI 
I.LOCi MVED l 
I,RECLEN = number] 
f,TR ANSID = number] 


SCHBFR (Search Buffer) 

SCHBFR [BFRNO = number] 
,RPL = address 
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SHOVVCB (Display Fields of an Access Method Control Block) 


| labei[ SHOVVCB ACB address 

,AREA = address 
,LENGTH » number 
f,OBJECT- {DATA | INDEX) 1 
,HELDS - (|ACBLEN||,AVSPAC|I,BFRFND| 
|,BSTRNO|I3Uraa||,BUFNI| 
|,BUFNO|f,BCFRDS||,BUFSP| 
|,CINVl(,DDNAME|f,ENDRBAl 
|,ERROR||,EXLST|[,FS| 
f,HALCRBA|(,KEYLENH,LRECL| 
|,MAREA|I,MLEN||,NCIS| 
|,NDELR||,NEXCP||,NEXT1 
|,NINSR||,NIXL||,NLOGRl 
|,NRETR||,NSSS||,NUIWI 
|,NUPDR||,PASSVVDI|,RKP| 

|,SIIRPOOL|(,STMSTJ[,STRMAXI 

|,STRNO|f,UIW]) 


SHOVVCB (Display Fields of an Exit List) 


|labeH SHOVVCB AREA - address 

,EXLST = address 
,LENGTH = number 

,FIELDS - (|EODAD||,EXLLEN|I,JRNAD) 
(,LERAD||,SYNAD|) 


SHOVVCB (Display Fields of a Request Parameter List) 


\'abel\ SHOVVCB AREA = address 

,LENGTH = number 
,RPL = address 

,HELDS - (|ACB||,AIXPC||,AREA| 

|,AREALENJ[,ARGJ[,ECB|I,FDBKJ 

|,FTNCD|l,KEYLENH,MSGAREA| 

[,MSGLENJ|,NXTRPL||,RBA| 

I,RECLEN||,RPLLENJ|,TRANSID| 
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TESTCB (Test a Field of an Access Method Control Block) 


| label\ TESTCB ACB = address 

|,ERET *= address] 

OBJECT = DATA | INDEX] 

,{ATRB = (|ESDS]|,KSDS]|,EDS]|,REPL| 
|,RRDS||,SPAN||,SSWD||,WCK|)| 
ATRB * UNQ 
CATALOG = {YES|NO) | 

MACRF = ([ADR|[,AIX||,CFX||,CNV||,DDN| 
|,DFR|I,DIR||,DSN]|,GSR|I,ICI| 
l>IN||,KEY||,LSR||,NCI|l»NDF] 
|,NFX||,NIS||,NRM||,NRS||,NSR| 
|,NUB||,OUT||,RST||,SEQ]I,SIS| 
l»SKP||,UBF|)| 

OFLAGS = OPEN | 

OPENOBJ = PATH|BASE| AIX j 
ACBLEN = number] 

AVSPAC = number] 

BSTRNO * number] 

BUFND = number] 

BUFNI = number] 

BUFNO = number] 

BUFSP = number] 

CINV = number] 

DDNAME = ddname] 

ENDRBA « number] 

ERROR = number] 

EXLST = address] 

FS= number] 

KEYLEN = number] 

LRECL = number] 

MAREA = address] 

MLEN = number] 

NCIS = number] 

NDELR = number] 

NEXCP = number] 

NEXT = number] 

NINSR * number] 

NIXL “ number] 

NLOGR = number] 

NRETR = number] 

NSSS = number] 

NUPDR = number] 

PASSWT) = address] 

RKP * number] 

SHRPOOL * number] 

STMST * address] 

STRNO = number) 
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TESTCB (Test a Field of an Exit List) 


[label} 


TESTCB 


,EXLST = address 
|,ERET = address\ 

,{EODAD * {0 \(\address\},\ | N J|,L|» | 
JRNAD= {0|(!arfdr»«U,A|NJ|,LD}l 

LERAD = {0|([^re^|I,A|\|[,LI>} | 
SYNAD = {0|(IaJc/re^||,A|\lI,L|»| 
(,EXLLEN = number] 


TESTCB (Test a Field of a Request Parameter List) 


\label\ 


TESTCB 


RPL = address 
|,ERET= address\ 

,(ACB = address] 

AIXFLAG = AIXPKPI 
AIXPC = number | 

AREA =* address\ 

ARKALEN = number\ 

ARC = address\ 

ECB = address | 

F'DBK = number\ 

FI’NCD = number\ 

KEYLEN = number\ 

MSG A REA = address j, 

MSGLKN = number\ 

NXTRPL = address\ 

IO* COMPLETEI 

OPTCD = (|ADR|I,ARD||,ASY||,BWDI|,C\V| 
|,DIR||,FKS||,F\VI)||,GEN||,KEQ| 
|,KEY||,KGE||,LOC||,LRl)||,MVE| 
|,NSP||,NUP|I,SEQ|!,SKP||,SYN| 
i,«jpL>i>i 
RBA = number] 

RECLEN = number\ 

RPLLEN = number\ 

TRANSID = number} 


VERIFY (Synchronize End of Data) 


| label} 

VERIFY 

RPL = address 



|,ACTION = REFRESH) 
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WRTBFR (Write Buffer) 


WRTBFR 


RPL = address 

,TYPE*{ALL|CHK|DRBA|DS|LRU(percem)|TRN} 
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Appendix B. List, Execute, and Generate Forms of Macros 


BLDVRP, DLVRP, GENCB, MODCB, SHOWCB, and TESTCB macros build 
a parameter list describing in codes the actions indicated by the operands you 
specify and pass the list to VSAM to take the indicated action. The list, execute, 
and generate forms of BLDVRP, DLVRP, GENCB, MODCB, SHOWCB, and 
TESTCB allow you to write reentrant programs, to share parameter lists, and to 
modify a parameter list before using it. 

Following is a brief description of the list, execute, and generate forms: 

• 'Ihc list form is used to build the parameter list cither inline (referred to as a 
simple list) or in an area remote from the macro expansion (referred to as a 
remote list). Both the simple- and the remote-list forms allow you to build a 
single parameter list that can be shared. 

• The execute form is used to modify a parameter list and to pass it to VSAM 
for action. 

• The generate form is used to build the parameter list in a remote area and to 
pass it to VSAM for action. 

The list, execute, and generate forms of the BLDVRP, DLVRP, GENCB, 
MODCB, SHOWCB, and TESTCB macros have the same format as the 
standard forms, with the exception of: 

• An additional keyword, MF 

• Keywords that are required in the standard form may be optional in the list, 
execute, and generate forms or may not be allowed in the execute form. The 
meaning of the keywords, however, and the notation that may be used to 
express addresses, names, numbers, and option codes arc the same. 

The sections that follow describe the format of the MF keyword and the use of 
list, execute, and generate forms. They also indicate the optional and invalid 
operands. 
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List-Form Keyword 


The format of the MF keyword for the list form is: 

MF = [L\(L,address\ y label[j) 

where: 

L 

specifies that this is the list form of the macro. 
address 

specifies the address of a remote area in which the parameter list is to be 
built. ITie area must begin on a fullword boundary. You can specify the 
address in register notation or as an expression valid for a relocatable 
A-type address constant or a direct or indirect S-type address constant. 

label 

is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 

Because the MF = L expansion docs not include executable code, register 
notation and expressions that generate S-type address constants cannot be used. 

If you code MF = L, the parameter lis£ is built inline, which means that the 
program is not reentrant if the parameter list is modified at execution. 

If you code MF = (L,address), the parameter list is built in the remote area 
specified, and the area must be large enough for the parameter list. 

The size, in fullwords, of a parameter list is: 

• For GENCB, 4, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For MODCB, 3, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For SHOWCB, 5, plus 2 times the number of fields specified in the FIELDS 
operand 

• For TESTCB, 8 (plus 1 for either DDNAME, STMST, EODAD, JRNAD, 
LERAD, or SYNAD) 

If you code MF = (L,address,label), the parameter list is built in the remote area 
specified. The expansion of the macro equates label with the length of the 
parameter list. 
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Execute-Form Keyword 


The format of the MF keyword for the execute form is: 

MF = (E ,address) 

where: 

E 

specifies that this is the execute form of the macro. 
address 

is the address of the parameter list. 

The expansion of the execute form of the macro results in executable code that 
causes: 

1. A parameter list to be modified if requested 

2. Control to be passed to a routine that satisfies the request 

You may not use the execute form to add an entry to a parameter list. If you try 
to add an entry, you will receive a return code of 8 in register 15. 


Generate-Form Keyword 

The format of the MF keyword for the generate form is: 

MF = {G,address\,label\) 

where: 

G 

specifies that this is the generate form of the macro. 
address 

specifics the address of a remote area in which the parameter list is to be 
built. 'I'he area must begin on a full word boundary. 


label 

is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 

If you code MF = (G,address), the parameter list is built in the remote area 
specified. 

If you code MF = (G,address,label), the parameter list is built in the remote area 
specified. The expansion of the macro equates the length of the parameter list to 
label. 
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List, Execute and Generate Formats 


List Form of BLDVRP 

Note: If FIX is specified, DLVRP must be issued by the same task that issues 
BLDVRP. STRNO is optional in the list form of BLDVRP, but, if it is not 
specified, it must be specified in the execute form. 

The format of the list form of BLDVRP is: 


BLDVRP 

BUFFERS = {size{ number) ^ize{ number) 


,MF=L 


I,FIX - {BFR|IOB|(BFR,IOB»| 


|,KEYLEN =■ length] 


LRMODE3! = fALL|BUFFICBINONE}| 


|,SIIRPOOL={0|n}| 


I,MODE * {24131} | 


I,STRNO =* number] 


f, TYPE = {LSRI.DATA | INDEXJjGSR} | 


Execute Form of BLDVRP 

Note: The address is the address of the parameter list built by a list form of 
BLDVRP. If you use register notation, you may use register 1, and a register 
between 2 and i2. Register I is used to pass the parameter list to VSAM. 
BUFFERS may not be specified in the execute form of BLDVRP, because this 
operand affects the length of the parameter list. 

The format of the execute form of BLDVRP is: 


BLDVRP 

MF = (E,address) 


|,KEYLEN = length] 


I.RMODE31 = {ALL1BUFFICBINONFJI 


|,SHRPOOL = number] 


f,MODE = {24|31}| 


|,STRNO = number] 


|,TYPE= {LSRLDATA|INDEXI|GSR}| 


Note: If MODE = 31 was specified on the list form, MODE = 31 must be 
specified on the execute form. The same is true for MODE = 24. 
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Execute Form of DLVRP 


Note: There is no list form for DLVRP, because DLVRP works with 
BLDVRP: It uses the parameter list associated with BLDVRP. The address is 
the address of the parameter list built by a list form of BLDVRP. If you use 
register notation, use register 1 to pass the address of the parameter list to 
VSAM. 

If MODE = 31 in the BLDVRP macro, then MODE = 31 is required in the 
DLVRP macro. 

The format of the execute form of DLVRP is: 


List Form of GENCB 


Execute Form of GENCB 


DLVRP 

MF = (E ,address) 

|,SHRPOOL *= number] 

|,MODE= {24|31)1 
,TYPE 88 (LSRjGSR) 

llic format of the list form of GENCB is: 

[label[ 

GENCB 

BLK= (ACB|EXLST|RPL) 

I.AM *= VSAMI 
|,COPIES * number] 

{^keyword — [address\name\number\option],...\ 

|,LENGTH = number] 

I.LOC = f BELOW I ANY) 1 

I.RMODE31 = 1ALL1BUFFICB1NONE] 1 
,M F = {L | (h,address],label])} 

|, WARE A = address | 

The format of the execute form of GENCB is: 

\label\ 

GENCB 

BLK = {ACB|EXLST|RPL) 

LAM * VSAMI 
|,COPIES = number] 

( Jceyword- [address\name\number\oplion] 

(,LENGTH = number] 

LLOC *= {BELOW | ANY) 1 

I.RMODE31 = (ALL! BUFFi CB i NONE) 1 
,MF= (E,address) 
j,WARE A = address] 
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Generate Form of GENCB 


The format of the generate form of the GENCB macro is: 


[label] 


GENCB 


BLK = {ACB|EXLST|RPL} 

LAM - VS AM? 
j, COPIES = number] 

[^keyword = address\name\number\option } ,...| 
|,LENGTH - number] 

|,LOC = {BELOW|ANY}| 

|,RMODE31 * {ALL|BLFF|CB|NONE}| 
,MF - (G,address],label]) 

|,WAREA = address | 


List Form of MODCB 


The format of the list form of MODCB is: 


{label] 


MODCB 


{ACB| EXLST| RPL{ = address 

,,keyword — [address\name\number\option],... 

,MF = {L \{L,address],label])} 


Execute Form of MODCB 


Note: If the execute form of MODCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB =. 

The format of the execute form of MODCB is: 


( label] 


MODCB 


|{ACB|EXLSI|RPL} = address] 
keyword = { address\name\number\option] 
,MF = (E,^ address) 


Generate Form of MODCB 

The format of the generate form of MODCB is: 


{label] 


MODCB 


{ACB|EXLST|RPL{ = address 
y keyword = {address]name]number\option },, 
,MF= {G,address],label[) 
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List Form of SHOWCB 


The format of the list form of SHOWCB is: 


[label\ 


SHOWCB 


|{ACB|EXLST|RPL} - address] 
,AREA = address 

,FIELDS = (keyword[,keyword,...]) 

,LENGTH = number 

,MF = [\.\(\.,address{,label])} 

,OBJECT «■ {DATA JINDEX) | 


Execute Form of SHOWCB 

The format of the execute form of SHOWCB is: 


[label] 

SHOWCB 

|{ACB|EXLST|RPL) = address 



,AREA = address 



,\1F = (E,address) 



f,OBJECT = (DATAIINDEX)I 


Generate Form of SHOWCB 

The format of the generate form of SHOWCB is: 


| label] 


SHOWCB 


|{ACB|EXLST|RPL) = address] 
,AREA = address 

^FIELDS = (keyword],key word,...]) 
,TENGUI = number 
,MF = (G,address],label]) 

|,OBJECT = ( DATA | INDEX) | 


List Form of TESTCB 


Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB =. 

The format of the list form of TESTCB is: 


( label] 


TESTCB 


|{ACB|EXLST|RPL) = address] 
j,ERET = address] 

keyword - { address\name | number] option],... 
,MF= [\A(b,address,label])] 

|,OBJECT = {DATA | INDEX) | 
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Execute Form of TESTCB 


Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB =. 

The format of the execute form of TESTCB is: 


Generate Form of TESTCB 


[label] 

TESTCB 

|{ACB|EXLST|RPL) = address] 

(,ERET = address | 

keyword - {address\name\number\option},... 

,MF = (E,address) 

I,OBJECT = {DATA 1 INDEX) | 

\ 

The format of the generate form of TESTCB is: 

[label] 

TESTCB 

!{ACB|EXLST|RPL) - address | 

|,ERET = address] 

keyword = { address\name \ number] option] 

,MF = (G ,address\,labe[[) 

|,OBJECT = {DATA! INDEX) I 


Use of List, Execute, and Generate Forms 

Figure 16 indicates which forms of GFNCB, MODCB, SIIOWCB, and 
TESTCB should be used in rcentrant/nonreentrant and shared/nonshared 
environments. 


Reentrant 

Shared M F = ( E,address\Jabel\) 

MF = (E,address) 

Nonsharcd MF = (G, address[, label]) 

Figure 16. Reentrant Programming 


Nonreentrant 
MF= L 

MF = (E,ad dress) 
Standard Form 


The figure shows that: 

• To share parameter lists in a reentrant program, the remote-list form should 
be used in conjunction with the execute form. 

• To share parameter lists in a nonreentrant program, the simple-list form 
should be used in conjunction with the execute form. 
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• If you do not intend to share parameter lists, the generate form should be 
used in reentrant programs and the standard form should be used for 
nonreentrant programs. 

Examples of Generate, List, and Execute Forms in Reentrant Environments 

The examples that follow illustrate how the list, execute, and generate forms 
work. 

Example: Generate Form (Reentrant) 


In this example, the generate form of GENCB is used to create a default request 
parameter list (RPL) in a reentrant environment. 


LA 

10,LEN1 

Get length of the parameter 

list. 

GETMAIN 

R,LV=(10) 

Get storage for the area in 
the parameter list is to be 

which 

built. 

LR 

2,1 

Save address of parameter-list 
area. 

GENCB 

BLK=RPL, 

MF=(G,(2),LEN1) 




The macro expansion equates LEN1 to the length of the parameter list, as 
follows: 

+LEN1 EQU 16 

The parameter list will be built in the area acquired by the GETMAIN macro 
-and pointed to by register 2. This list is used by VS AM to build the RPL. 

VS AM returns the RPL address in register 1 and the RPL length in register 0. If 
the WAREA and LENGTH parameters are used, the RPL will be built at the 
VVAREA address. 


Example: Rcmotc-List Form (Reentrant) 


In this example, the remote-list form of MODCB is used to build a parameter list 
that will later be used to modify the MACRF bits in the access method control 
block ANYACB. 


LA 8,LEN2 Get length of the parameter 

list. . 

GETMAIN R,LV=(8) Get storage for the area in 

which the parameter list is to 
be built. 


LR 3,1 Save address of the 

parameter-list area. 

MODCB ACB=ANYACB, 

MACRMF=(L,(3),LEN2) 


The macro expansion equates the length of the parameter list to LEN2, as 
follows: 

+LEN2 EQU 24 
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This parameter list is built in the remote area pointed to by register 3. The list 
will be used by VSAM to modify the ACB when an execute form of MODCB is 
issued (see next example). The list form only creates a parameter list; it does not 
modify the ACB. 

Example: Execute Form (Reentrant) 

In this example, the execute form of MODCB is used to modify the address of 
the access method control block and MACRF codes in the parameter list created 
by the remote-list form of MODCB in the previous example. 

MODCB ACB=MYACB,MACRF=(ADR,SEQ,OUT),MF=(E,(3)) 

The parameter list pointed to by register 3 is changed so that the ACB and 
MACRF parameter values in the execute form override those in the list form. 
The access method control block, MYACB, is then modified to 
MACRF = ADR,SEQ,OUT). The access method control block at ANYACB is 
not changed by either of these examples. 
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Appendix C. Operand Notation 


Operands with GENCB, MODCB, SHOWCB, and TESTCB 

The addresses, names, numbers, and options required with operands in GENCB, 

MODCB, SIIOWCB, and TESTCB can be expressed in a variety of ways: 

• An absolute numeric expression, for example, STRNO = 3 and COPIES = 10. 

• A code or a list of codes separated by commas and enclosed in parentheses, for 
example, OPTCD= KEY or OPTCD = (KEY,DIR,IN). 

• A character string, for example, DDNAME= DATASET. 

• A register from 2 through 12 that contains an address or numeric value, for 
example, SYNAD = (3); equated labels can be used to designate a register, for 
example, SYNAD = (ERR), where the following equate statement has been 
included in the program: ERR EQU 3. 

• An expression of the form (S^con), where scon is an expression valid for an 
S-type address constant, including the base-displacement form. The contents 
of the base register will be added to the displacement to obtain the value of 
the keyword. For example, if the value of the keyword being represented is a 
numeric value (that is, COPIES, LENGTH, RECLEN), the contents of the 
base register will be added to the displacement to determine the numeric 
value. If the value of the keyword being represented is an address constant 
(that is, WAREA, EXLST, EODAD, ACB), the contents of the base register 
will be added to the displacement to determine the value of the address 
constant. 

• An expression of the form (*,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form; the address 
specified by scon is indirect, that is, it is the address of an area that contains 
the value of the keyword. The contents of the base register will be added to 
the -displacement to determine the address of the fullword of storage that 
contains the value of the keyword. 

If an indirect S-type address constant is used, the value it points to must meet 
the following criteria: 

- If it is a numeric quantity or an address, it must occupy a fullword of 
storage. 
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— If it is an alphameric character string, it must occupy two words of 
storage, be left aligned, and be filled on the right with blanks. 

• An expression valid for a relocatable A-type address constant, for example, 
AREA = MYAREA + 4. 

The specified keyword determines the type of expressions that can be used. 
Additionally, register and S-type address constants cannot be used when MF= L 
is specified. 


The tables containing the individual macro operand notations have been deleted 
from this release. This information may be obtained from the individual macro 
descriptions shown in Chapter 2, “VSAM Macro Formats and Examples”. 
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Appendix D. Building Parameter Lists 


The standard forms of GENCB, MODCB, SHOWCB, and TESTCB build a 
parameter list, put its address in register 1, and pass control to a VS AM routine 
to generate, modify, display, or test an access method control block, exit list, or 
request parameter list. Other forms of the macros only build the parameter list 
(list forms) or only pass control to VSAM (execute forms). 

You can avoid using a macro to build the parameter list by building it yourself 
and issuing the execute form of the macro to pass control to VSAM. This 
chapter explains how to build the parameter lists for GENCB, MODCB, 
SIIOWCB, and TESTCB. ITie rules for combinations of codes in a parameter 
list arc the same as the rules for combinations of operands in a macro. 

You can avoid issuing the execute form of the macro by coding the linkage 
instructions that pass control directly to the VSAM control block manipulation 
routine. Before passing control, you must build the parameter list yourself. 


The Format of the Parameter Lists 

A parameter list for GENCB, MODCB, SHOWCB, or TESTCB is a list of 
fullword addresses. The first address points to a header entry that identifies the 
type of request and type of control block and gives other general information 
about the request. Each of the rest of the addresses in the parameter list points 
to an element entry that identifies the information you want to generate, modify, 
display, or test. 

The fullwords in the parameter list must be contiguous, and the last one must 
have a 1 in its first bit. ITie header entry and each clement entry may be separate 
from each other. Figure 17 on page 184 gives the formats of the header and 
element entries for the four request types. 
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Header Entry 


Generation 

GENCB 


u GENBTC GENFTC 

Control- Function 

block type type 

4 GENUSA (optional) 

Address of area provided 
for generation 

8 GENUSL (optional) ( 
Length of area 


GENFTC 

GENCOP 

0 

ELEMKWTC 

Function 

Number of copies 


Keyword 

type 

of block 


type 


(reserved) 


Element Entry 

I (reserved) 


Keyword value 


(required for 
some keywords)’* 


Modification 0 

MODCB 

MODBTC 

Control- 
block type 

MODFTC 

Function 

type 

(reserved) 

0 

ELEMKWTC 

Keyword 

type 

■ 4 

MODBLAD 



4 



Address of control block 



Keyword value 


to be modified 








8 



(required for 
some keywords)” 


(reserved) 


Display 

SHOWCB 


(optional) 
Control- 
block type 


SHOWFTC 

SHOWOBJ 

0 

ELEMKWTC 

(reserved) 

Function 

Object type 


Keyword 


type 

(data or index) 


type 



Address of control 
block to be displayed 

8 SHOWUSA 

Address of area provided 
for display 


SHOWUSL 
Length of area 


(reserved) 


(reserved) 


Test 0 TESTBTC TESTFTC TESTOBJ 0 ELEMKWTC I (reserved) 

TESTCB (optional) _ . ... „ 

Control- Function Object type Keyword 

block type type (data or index > type 

4 TESTBLAD (optional) 4 

Address of control Keyword value 

block to be tested 

8 TESTERET (optional) 8 (iequit ed for 

Address of error-analysis I some keywords)* 

routine (ERET) s 

12 (reserved) 

^Second fullword required for 
keyword value of DDNAME, • 

___ STMST, EODAD, JRNAD, 

LERAD, and SYNAD. 

Figure 17. Format of Header and Element Entries for GENCB, MODCB, SHOWCB, and TESTCB Parameter Lists 


Keyword value 


(required for 
some keywords)* 
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Building Header and Element Entries 


Five assembler macros are provided for building entries. 

IDAGENC, IDAMODC, IDASHOW, and IDATEST help you build a header 
entry for generation, modification, display, or test. IDAELEM helps you build 
an element entry. 


\label\ 

IDAGENC 

| DSECT = (YESINOH 

\labe!\ 

IDAMODC 

| DSECT = (YESINOH 

| label\ 

IDASIIOVV 

(DSECT = f YESINOH 

\label\ 

IDATEST 

(DSECT = (YESINOH 

\label\ 

IDAELEM 

(DSECT = (YESINOH 


DSECT - f YES I NO) 

Indicates whether a DSECT statement is to be generated. If you intend to 
build entries in a continuous area, you could have only the first of the 
macros generate a DSECT statement and use a single register to address the 
whole area. 

These macros generate labeled DS statements that give the layout of an entry and 
EQU statements that equate a label with a numeric code. You can symbolically 
encode an entry with a scries of move instructions. The macros arc 
self-documenting— inspect a listing of their expansions and you can sec which 
labels to code in your move instructions. (You can list the macros as they 
appear in the macro library.) 

To generate an exit list with LEkAD and SYNAD exits, you could code a 
GENCB of the standard form: 

GENCB BLK=EXLST, LERAD=('LOGERR, L) , SYNAD=PHYSERR 

The following example shows how to achieve the same effect by building the 
parameter list and entries yourself and issuing a GENCB of the execute form. 

Set up base register for 
the entries. 

GENC is the first label in 
the work area. 

point to the entries. 

Address of the header 
entry. 

Address of the first 
element entry. GENLEN is 
equated to the length of 
a header element for 
generation. 

ST 6,PLIST+4 


LA 5,NTRYAREA 

USING 5,GENC 

Build the list of addresses that 

ST 5,PLIST 

LA 6,GENLEN(,5) 
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LA 

6,ELEMLLEN(,6) 

Address of the second 
element entry. ELEMLLEN 
is equated to the length 
of an element entry for 
an exit list. 



ST 

6,PLIST+8 




01 

plist+s.x'so* 

End-of-list indicator. 

Build 

the 

header 

entry. 




MV I 

GENBTC,GENXLST 

Indicate the 
blocktype-exit list. 



MV I 

GENFTC,GENFTYP 

Indicate the function 
type-generation. 



MV I 

GENC0P+l,X'0l' 

Indicate the number of 
copies of the exit list 
to be generated. 



MV I 

ELEMKWTC+1, 

ELEMLEAD 

Indicate the keyword type- 
LERAD. 



LA 

6,LOGERR 

Address of the name of the 
logical error analysis 
module. 



ST 

6,ELEMPTR 




MV I 

ELEMXFLG, 

ELEMXLHrELEMXADR 

Indicate the presence of 
as. address ELEMPTR and 
that the exit routine is 
to be loaded. 

Build 

the 

second 

element entry. 




LA 

5,ELEMLLEN(,5) 

Align the DSECT with the 
second element entry. 
ELEMLLEN is equated to the 
length of an element entry 
for an exit list. 



MVI 

ELEMKWTC+1, 

ELEMSYAD 

Indicate the keyword 
type-SYNAD. 



LA 

6,PHYSERR 

Address of the entry point 
of the physical error 
analysis routine. 



ST 

6,ELEMPTR 




MVI 

ELEMXFLG, 

ELEMXADR 

Indicate the presence of 
an address in ELEMPTR. 

Pass control to VSAM. 




GENCB 

MF=(E,PLIST) 




LTR 

15,15 

Generation successful? 



BNZ 

CHECKO 

No. 
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CHECKO 


ABEND l.DUMP 


Register 0 indicates the 
error. 


Physical error analysis exit routine. 
PHYSERR . . . 


Work areas and constants. 
LOGERR DC CL8’LEM0D' 

PLIST DC 3F'0' 


NTRYAREA DC gF’O' 


Name of the 

logical error analysis 

module to be loaded. 

List of entry addresses. 

3 addresses are 
required: 1 for the header 
and 2 for the elements 
(1 for LERAD and 1 for 
SYNAD). 

Work area for header and 
element entries. The 
header for GENCB is 3 
fullwords, and so are 
the LERAD and SYNAD 
elements. 


DSECT with labels for the header and element entries. 

IDAGENC Header entry. A DSECT 

statement is generated, 
and register 5 is used 
to address NTRYAREA 
with these labels. 

IDAELEM DSECD=NO Element entry. Element 

labels are part of the 
same DSECT as the 
header labels. 


Passing Control Directly to VSAM 


You can avoid using the execute form of GENCB, MODCB, SIIOWCB, and 
TESTCB by building your own linkage instructions. You first build a parameter 
list, as described in the previous section, and put its address in register 1. Then 
you pass control to VSAM using the following instructions: 


L 15,16 

L 15,256(,15) 

L 15,12(,15) 

BALR 14,15 


Put the address of the CVT 
into register 15. 

Put the address of the AMCBS 
control block into register 15. 

Put the address of the control 
block manipulation routine into 
register 15. 

Branch to the routine 


The BALR 14,15 instruction is used when the specific function (GENCB, 
MODCB, SHOWCB, or TESTCB) is not known, or when the control block 
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type (ACB, EXLST, or RPL) is not known. The user-built parameter list 
contains the function code and control block type code. 


Decimal 


Value of xx 

Function 

Control Block 

8 

GENCB 

ACB 

12 

GENCB 

RPL 

16 

GENCB 

EXLST 

20 

Reserved 


24 

MODCB 

ACB 

28 

MODCB 

RPL 

32 

MODCB 

EXLST 

36 

Reserved 


40 

SIIOWCB 

ACB 

44 

SIIOWCB 

RPL 

48 

SIIOWCB 

EXLST 

52 

Reserved 


56 

TESTCB 

ACB 

60 

TESTCB 

RPL 

64 

TESTCB 

EXLST 

68 

Reserved 


72 

SIIOWCB or 

Block length 


TESTCB 

keywords only 

76‘ 

SIIOWCB 

RECLEN field 



of an RPL 

80‘ 

MODCB 

RECLEN field 
of an RPL 


1 Register 1 points to an RPL when xx is 76 or 80. See the following section 
for details. 

When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the task completed successfully. Otherwise, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 

Modifying and Displaying the RECLEN Field of an RPL Directly 

You can modify or display the RECLEN field (that is, the record length) of an 
RPL without issuing a SIIOWCB or MODCB macro, and without building a 
parameter list. 

To modify a RPL's RECLEN field, you first put the address of the RPL in 
register 1, and the value to be set in the RECLEN field in register 0. Next, you 
code the instructions that put the address of the VSAM control block 
manipulation routine into register 15, then branch to the routine: 
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L 15,16 Put the address of the CVT into 

register 15. 

L 15,256(,15) Put the address of the AMCBS 

control block into register 15. 


L 15,12(,15) 

BAL 14,80(,15) 


Put the address of the control 
block manipulation routine 
into register 15. 

Branch to the routine. 


When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the field was modified correctly. Otherwise, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 


To display the contents of a RPL's RliCLEN field, you first put the address of 
the RPL in register 1. Next, you code the instructions that put the address of the 
VSAM control block manipulation routine into register 15, and then branch to 
the routine: 


L 15,16 Put the address of the CVT into 

register 15. 

L 15,256(,15) Put the address of the AMCBS 

control block into register 15. 


L 15,12(,15) 

BAL 14,76(,15) 


Put the address of the control 
block manipulation routine into 
register 15. 

Branch to the routine. 


When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the field is displayed correctly, and register 0 
contains the value of the RPL's RECLHN field. When register 15 is not zero, 
register 15 and register 0 contain codes that identify the reason VSAM could not 
complete the task. 
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Glossary of Terms and Abbreviations 


The following terms arc defined as they are used in this 
book. If you do not find the term you are looking for, 
sec the index or the IBM Vocabulary for Data 
Processing, Telecommunications, and Office Systems, 
GC20-1699. 

ACB. (See access method control block.) 

access method control block. A control block that links 
an application program to VSAM or ACF/VTAM. 

access method services. A multifunction service 
program that is used to define VSAM data sets and 
allocate space for them, convert indexed-sequential data 
sets to key-scqucnccd data sets, modify data set 
attributes in the catalog, reorganize data sets, facilitate 
data portability between operating systems, create 
backup copies of data sets, help make inaccessible data 
sets accessible, list the records of data sets and catalogs, 
define and build alternate indexes, and convert OS 
CVOLs and VSAM catalogs to integrated catalog 
facility catalogs. 

acquire. To allocate space on a staging drive and to 
stage data from an MSS cartridge to the staging drive. 

addressed-direct access. The retrieval or storage of a 
data record identified by its RBA, independent of the 
record's location relative to the previously retrieved or 
stored record. (See also keyed-direct access, addressed- 
sequcntial access, and keyed-sequential access.) 

addrcsscd-scqucntial address. The retrieval or storage of 
a data record in its entry sequence relative to the 
previously retrieved or stored record. (See also 
keyed-sequential access, addressed-direct access, and 
keyed-direct access.) 

alternate index. A collection of index entries organized 
by the alternate keys of its associated base data records. 
It provides an alternate means of locating records in the 
data component of a cluster on which the alternate 
index is based. 

alternate index cluster. The data and index components 
of an alternate index. 

alternate key. One or more consecutive characters 
taken from a data record and used to build an alternate 


index or to locate one or more base data records’ via an 
alternate index. (See also generic key, key, and key 
field.) 

APF. (See authorized program facility.) 

application. As used in this publication, the use to 
which an access method is put or the end result that it 
serves; contrasted to the internal operation of the access 
method. 

authorized program facility. A facility that permits the 
identification of programs that arc authorized to use 
restricted functions. 

base cluster. A kcy-scqucnced or cntry-sequcnccd data 
set over which one or more alternate indexes are builL 

base RBA. The RBA stored in the header of an index 
record that is used to calculate the RBAs of data or 
index control intervals governed by the index record. 

catalog. (See master catalog and user catalog.) 

catalog recovery area. An cntry-sequcnccd file that 
exists on each volume owned by a recoverable catalog, 
including the catalog itself. The CRA contains records 
that are duplicates of the catalog entries describing the 
volume and the files it contains. 

CBIC. Control blocks in common, a facility that allows 
a user to open a VSAM data set so the VSAM control 
blocks arc placed in the common service area (CSA) of 
the MVS operating system. 1Tiis provides the capability 
for multiple memory accesses to a single VSAM control 
structure for the same VSAM data set. 

chained RPL. (See RPL string.) 

Cl. (See control interval.) 

CIDF. (See control interval definition field.) 

cluster. A named structure consisting of a group of 
related components (for example, a data component 
with its index component). A duster may consist of a 
single component (See also base cluster and alternate 
index cluster.) 
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collating sequence. An ordering assigned to a set of 
items, such that any two sets in that assigned order can 
be collated. 

component. A named, cataloged collection of stored 
records. A component, the lowest member of the 
hierarchy of data structures that can be cataloged, 
contains no named subsets. 

control area. A group of control intervals used as a unit 
for formatting a data set before adding records to it. 
Also, in a kcy-scqucnced data set, the set of control 
intervals pointed to by a sequcnce-sct index record; used 
by VS AM for distributing free space and for placing a 
scqucnce-set index record adjacent to its data. 

control area split. The movement of the contents of 
some of the control intervals in a control area to a 
newly created control area, to facilitate the insertion or 
lengthening of a data record when there arc no 
remaining free control intervals in the original control 
area. 

control interval. A fixed-length area of auxiliary storage 
space in which VSAM stores records. It is the unit of 
information transmitted to or from auxiliary storage by 
VSAM. 

control interval access, llic retrieval or storage of the 
contents of a.control interval. 

control interval definition field. In VSAM, the 4-byte 
control information field at the end of a control interval 
that gives the displacement from the beginning of the 
control interval to free space and the length of the free 
space. If the length is 0, the displacement is to the 
beginning of the control information. 

control interval split. The movement of some of the 
stored records in a control interval to a free control 
interval, to facilitate the insertion or lengthening of a 
record that won't fit in the original control interval. 

control volume. A volume that contains one or more 
indexes of the catalog. 

CRA. (See catalog recovery area.) 

cross memory. A synchronous method of 
communication between address spaces. 

CVOL. (See control volume.) 

DASD. (See direct access storage device.) 

data record. A collection of items of information from 
the standpoint of its use in an application, as a user 
supplies it to VSAM for storage. 


data set. The major unit of data storage and retrieval 
in the operating system, consisting of data in a 
prescribed arrangement and described by control 
information to which the system has access. As used in 
this publication, a collection of fixed- or variable-length 
records in auxiliary storage, arranged by VSAM in key 
sequence or in entry sequence. (See also key-sequenced 
data set and entry-sequenced data set) 

l)D statement, data definition statement 

direct access. The retrieval or storage of data by a 
reference to its location in a data set rather than relative 
to the previously retrieved or stored data. (See also 
addressed-direct access and keyed-direct access.) 

direct access storage device. A device in which the 
access time is effectively independent of the location of 
the data. 

EBDIC. Extended binary-coded decimal interchange 
code. A coded character set consisting of 8-bit coded 
characters. 

entry sequence. The order in which data records are 
physically arranged (according to ascending RBA) in 
auxiliary storage, without respect to their contents. 
(Contrast with key sequence.) 

entry-sequenced data set. A data set whose records are 
loaded without respect to their contents, and whose 
RBAs cannot change. Records are retrieved and stored 
by addressed access, and new records are added at the 
end of the data set 

EOD. end of data 

EOKR. end-of-key range 

EOV. end of volume 

field. In a record or a control block, a specified area 
used for a particular category of data or control 
information. 

free control interval pointer list. In a sequence-set index 
record, a vertical pointer that gives the location of a free 
control interval in the control area governed by the 
record. 

free space. Space reserved within the control intervals 
of a kcy-scqucnced data set for inserting new records 
into the data set in key sequence; also, whole control 
intervals reserved in a control area for the same 
purpose. 

GENDSP. An option of LOCATE to obtain the 
control interval number of the catalog record of each 
object 
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generation data group. A collection of data sets that are 
kept in chronological order; each data set is called a 
generation data set. 

generic key. A high-order portion of a key, containing 
characters that identify those records that are significant 
for a certain application. For example, it might be 
desirable to retrieve all records whose keys begin with 
the generic key AB, regardless of the full key values. 

global shared resources. An option for sharing I/O 
buffers, I/O-rclatcd control blocks, and channel 
programs among VS AM data sets in a resource pool 
that serves all address spaces in the system. 

GSR. (See global shared resources.) 

header, index record. In an index record, the 24-byte 
field at the beginning of the record that contains control 
information about the record. 

header entry. In a parameter list of GENCB, MODCB, 
SIIOVVCB, or TF.STCB, the entry that identifies the type 
of request and control block and gives other general 
information about the request. 

horizontal pointer. In the header of an index record, the 
RBA of the index record in the same level as this one 
that contains keys next in ascending sequence after the 
keys in this one. 

index. As used in this publication, an ordered collection 
of pairs, each consisting of a key and a pointer, used by 
VS AM i<5 sequence and locate the accords of a 
key-sequenced data set. 

index level. A set of index records that order and give 
the location of all the control intervals in the next lower 
level or in the data set that it controls. 

index record. A collection of index entries that are 
retrieved and stored as a group. (Contrast to data 
record.) 

index record header. In an index record, the 24-bytc 
field at the beginning of the record that contains control 
information about the record. 

index replication. The use of an entire track of direct 
access storage to contain as many copies of a single 
index record as possible; reduces rotational delay. 

index set. The set of index levels above the sequence 
set. The index set and the sequence set together 
comprise the index. 

integrated catalog facility. The name of the catalog 
associated with the Data Facility Product program 
product. 


IOPID. I/O prevention identifier which is used to 
terminate I/O and prevent new I/O from being started. 

ISAM, indexed sequential access method 

ISAM interface. A set of routines that allow a 
processing program coded to use ISAM (indexed 
sequential access method) to gain access to a 
key-sequenced data set. 

JCL. (See job control language.) 

job catalog. A catalog made available for a job by 
means of the JOBCAT DD statement. 

job control language. A problem-oriented language 
designed to express statements in a job that arc used to 
identify the job or describe its requirements to an 
operating system. 

job step catalog. A catalog made available for a job by 
means of the STF.PCAT DD statement 

key. One or more characters within an item of data 
that arc used to identify it or control its use. As used in 
this publication, one or more consecutive characters 
taken from a data record, used to identify the record 
and establish its order with respect to other records. 

(See also key field and generic key.) 

key field. A field located in the same position in each 
record of a data set, whose contents arc used for the key 
of a record. 

key sequence. The collating sequence of data records, 
determined by the value of the key field in each of the 
data records. May be the same as, or different from, 
the entry sequence of the records. 

key-sequenced data set. A VS AM file (data set) whose 
records arc loaded in key sequence and controlled by an 
index. Records are retrieved and stored by keyed access 
or by addressed access, and new records are inserted in 
key sequence by means of distributed free space. 

Relative byte addresses of records can change because 
of control interval or control area splits. 

keyed-direct access. The retrieval or storage of a data 
record by use of cither an index that relates the record's 
key to its relative location in the data set or a relative 
record number, independent oi the record's location 
relative to the previously retrieved or stored record. 

(See also addresscd-direct access, keyed-sequential 
access, and addressed-sequential access.) ^ 

keyed-sequential access. The retrieval ohstorage of a 
data record in its key or relative record sequence relative 
to the previously retrieved or stored record, as defined 
by the sequence set of an index. (See also 
addressed-sequential access, keyed-direct access, and 
addressed-direct access.) 
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level number. For the index of a key-sequenced data 
set, a binary number in the header of an index record 
that indicates the index level to which the record 
belongs. 

| linear data set (LDS). A named linear string of data, 

| stored in such a way that it can be retrieved or updated 
j in 4096 byte units. An LDS object is essentially a 
| VSAM entry-sequenced data set that is processed as a 
j control interval. I lowcvcr, unlike a control interval, an 
| LDS contains data only, that is, it contains no record 
j definition fields (RDFs) or control interval definition 
j fields (CIDFs). 

local shared resources. An option for sharing I/O 
buffers, I/O-related control blocks, and channel 
programs among VSAM data sets in a resource pool 
that serves one partition or address space. 

| LDS. (See linear data set) 

LSR. (See local shared resources.) 

master catalog. A catalog that contains extensive data 
set and volume information that VSAM requires to 
locate data sets, to allocate and deallocate storage space, 
to verify the authorization of a program or operator to 
gain access to a data set, and to accumulate usage 
statistics for data sets. 

operating system. Software that controls the execution 
of programs; an operating system may provide services 
such as resource allocation, scheduling, input/output 
control, and data management. 

password. A unique string of characters stored in a 
catalog that a program, a computer operator, or a 
terminal user must supply to meet security requirements 
before a program gains access to a data set. 

path. A named, logical entity composed of one or more 
clusters (an alternate index and its base cluster, for 
example). 

physical record. A physical unit or recording on a 
medium. For example, the physical unit between 
address markers on a disk. 

pointer. An address or other indication of location. 

For example, an RBA is a pointer that gives the relative 
location of a data record or a control interval in the 
data set to which it belongs. 

prime index. The index component of a key-sequenced 
data set that has one or more alternate indexes. (See 
also index and alternate index.) 

prime key. (See key.) 

QSAM. (See queued sequential access method.) 


queued sequential access method. An extended version 
of the basic sequential access method (BSAM). When 
this method is used, a queue is formed of input data 
blocks that are awaiting processing or output data 
blocks that have been processed and arc awaiting 
transfer to auxiliary storage or to an output device. 

RACF. Resource Access Control Facility. 

random access. (See direct access.) 

RBA. Relative byte address. The displacement 
(expressed as a fuliword binary integer) of a data record 
or a control interval from the beginning of the data set 
to which it belongs; independent of the manner in which 
the data set is stored. 

RDF. (See record definition field.) 

record. (See index record, data record.) 

record definition field. A field stored as part of a stored 
record segment; it contains the control information 
required to manage stored record segments within a 
control interval. 

relative byte address. (See RBA.) 

relative record data set. A data set whose records arc 
loaded into fixed-length slots. 

relative record number. A number that identifies not 
only the slot, or data space, in a relative record data set 
but also the record occupying the slot. Used as the key 
for keyed access to a relative record data set. 

replication. (See index replication.) 

request parameter list. A control block that contains 
the information needed to process an 1,0 request 

resource pool, VSAM. (See VSAM resource pool.) 

reusable data set. A VSAM data set that can be reused 
as a work file, regardless of its old contents. Must not 
be a base cluster. 

RI*L. (See request parameter list.) 

RPL string. A set of chained RPl.s (the set may 
contain one or more RPLs) used to gain access to a 
VSAM data set by action macros (GET, PUT, etc). 
Two or more RPL strings may be used for concurrent 
direct or sequential requests made from a processing 
program or its subtasks. 

SAM. (See sequential access method.) 

security. (See data security.) 
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sequence checking. The process of verifying the order 
of a set of records relative to some field's collating 
sequence. 

sequence set. The lowest level of the index of a 
key-sequenced data set; it gives the locations of the 
control intervals in the data set and orders them by the 
key sequence of the data records they contain. The 
sequence set and the index set together comprise the 
index. 

sequential access. The retrieval or storage of a data 
record in either its entry sequence, its key sequence, or 
its relative record number sequence, relative to the 
previously retrieved or stored record. (See also 
addressed-sequential access and keyed-sequential 
access.) 

sequential access method. An access method for storing 
or retrieving data blocks in a continuous sequence, using 
cither a sequential access or a direct access device. 

shared resources. A set of functions that permit the 
sharing of a pool of I O-related control blocks, channel 
programs, and buffers among several VS AM data sets 
open at the same time. 

skip-sequential access. Keyed-sequential retrieval or 
storage of records here and there throughout a data set, 
skipping automatically to the desired record or collating 
position for insertion: VS AM scans the sequence set to 
find a record or a collating position. Valid for 
processing in ascending sequences only. 

slot. For a relative record data set, the data area 
addressed by a relative record number which may 
contain a record or be empty. 

spanned record. A logical record whose length exceeds 
control interval length, and as a result, crosses, or spans, 
one or more control interval boundaries within a single 
control area. 

SRB. Service request block. A system control block 
used for dispatching tasks. 

step catalog. A catalog made available for a step by 
means of the STEPCAT l)i) statement. 

terminal monitor program. In TSO, a program that 
accepts and interprets commands from the terminal, and 
causes the appropriate command processors to be 
scheduled and executed. 

time sharing option. An optional configuration of the 
operating system that provides conversational time 
sharing from remote stations. 

TMP. (See terminal monitor program.) 


transaction ID. A number associated with each of 
several request parameter lists that define requests 
belonging to the same data transaction. 

TSO. (See time sharing option.) 

update number. For a spanned record, a binary 
number in the second RDF of a record segment that 
indicates how many times the segments of a spanned 
record should be equal. An inequality indicates a 
possible error. 

upgrade set. All the alternate indexes that VS AM has 
been instructed to update whenever there is a change to 
the data component of the base cluster. 

user buffering. The use of a work area in the processing 
program's address space for an I/O buffer; VSAM 
transmits the contents of a control interval between the 
work area and direct access storage without 
intermediary buffering. 

user catalog. An optional catalog used in the same way 
as the master catalog and pointed to by the master 
catalog. It also lessens the contention for the master 
catalog and facilitates volume portability. 

vertical pointer. A pointer in an index record of a given 
level that gives the location of an index record in the 
next lower level or the location of a control interval in 
the data set controlled by the index. 

virtual storage access method. An access method for 
direct or sequential processing of fixed and 
variable-length records on direct access devices. The 
records in a VSAM data set or file can be organized in 
logical sequence by a key field (key sequence), in the 
physical sequence in which they are written on the data 
set or file (entry sequence), or by relative record 
number. 

| virtual telecommunications access method. A set of 
J programs that control communication between terminals 
j and application programs running under VSE, OS VS1, 

| and OS/VS2. 

VSAM. (See virtual storage access method.) 

VSAM resource pool. A virtual storage area that is 
used to share I/O buffers, l/O-rclatcd control blocks, 
and channel programs among VSAM data sets. A 
resource pool is local or global; it serves tasks in one 
partition or address space or tasks in all address spaces 
in the system. 

VSAM shared information. Blocks that are used for 
cross-system sharing. 

VSI. (See VSAM shared information.) 


Glossary of Terms and Abbreviations 195 



| VTAM. {See virtual telecommunications access 
| method.) 
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keyed-direct deletion, ERASE macro 63 
keyed-direct insertion, PU T macro 118 
keyed-direct update, PUT macro 121 
keyed-sequential insertion, PUT macro 111, 115 
keyed-sequential retrieval (backward), G ET 
macro 87 

keyed-sequential retrieval, GET macro- 86- 
keyed-sequential update, PUT macro 120 
loading a relative record data set, PUT macro 113 
marking records inactive, PUT macro 124 
modify a request parameter list, MODCB 
macro 105 

modify an exit list, MODCB macro 103 
modify name of exit list in ACB, MODCB 
macro 101 

obtain LSR above 16M, BLDVRP macro 49 
obtaining resource pool above 16M, BLDVRP 
macro 49 

open macro with parameter list above 16M, OPEN 
macro 108 

open two data sets, OPEN macro 108 
overlay processing, CHECK macro 52 
position, POINT macro 109 
recording RBAs when loading, PUT macro 112 
release positioning, ENDREQ macro 61 
request separate data and index pools, BLDVRP 
macro 50 

request separate data/index resource pools, 
BLDVRP macro 50 

retrieving a keyed-direct record, GET macro 92 
retrieving a relative record sequentially, GET 
macro 91 

retrieving an addressed-direct record, GET 
macro 93 

retrieving direct to sequential record, GET 
macro 94 

ski-sequential retrieval, GET macro 87 
skip-sequential insertion, PUT macro 116 


suspend many record request, CHECK macro 53 
test a request parameter list, TESTCB macro 154 
test for data set attributes, TESTCB macro 148 
use a branch table, TESTCB macro 151 
example of generate, list, execute forms in reentrant 
environment 179 
execute form 

BLDVRP macro 174 
DLVRP macro 175 
GENCB macro 175 
MODCB macro 176 
SHOWCB macro 177 
TESTCB macro 178 
use of 178 

execute-form keyword 173 
execution time 

generate a request parameter list, summary 162 
generate an ACB 69 

generate an access method control block 161 
generate an exit list, summary 162 
generate exit list 76 
generate request parameter list 80 
exit list 

address displayed in SHOWCB macro 
example 138 

fields displayed in SHOWCB macro 139 
generating at execution time 76 
generating in EXLST macro 66 
length displayed in SHOWCB macro example 140 
EXLLEN parameter 

in SHOWCB macro 139 
in TESTCB macro 151 
EXLST macro 
example 67 
format 66 

generate exit list at assembly time 
summary 161 
EXLST parameter 
in ACB macro 37 
in FIELDS parameter 135 
in GENCB macro 72 
in MODCB macro 102 
in SHOWCB macro 139 
in TESTCB macro 150 


0 

FDBK parameter 

in FIELDS parameter 142 
feedback word in the RPL 13 
FIELDS parameter 

in SHOWCB macro 134, 139, 142 
FIX parameter 

BLDVRP macro 46 
FKS subparameter 

in OPTCD parameter of RPL macro 130 
format 

ACB macro 34 
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ACQRANGE macro 44 
BLDVRP macro 46 
CHECK macro 51 
CLOSE macro 55 
CNVTAD macro 57 
DLVRP macro 59 
ENDREQ macro 61 
ERASE macro 63 
execute form 

of BLDVRP macro 174 
of DLVRP macro 175 
EX LS I' macro 66 
GENCB macro 69 
G El' macro 86 
GETIX macro 97 
list form 

of BLDVRP macro 174 
MNTACQ macro 98 
MODCB macro 100 
MRKBFR macro 106 
OPEN macro 107 

parameter lists of GENCB, MODCB, SIIOWCB, 
and TESTCB macros 
address list 185 
element entry 185 
header entry 185 
POI NX-macro 109 
PUT mach> 111 
PUTIX macro 125 
RPL macro 126 
SCI1BFR macro 132 
SIIOWCB macro 133 
TESTCB macro 145,150 
VERITY macro 155 
W RIB PR macro 156 
format of the parameter lists 183 
PS parameter 

in FIELDS parameter 136 
PTNCD parameter 

in FIELDS parameter 142 
in TESTCB macro 153 
FWD subparameter 

in OPTCD parameter of RPL macro 129 


G 


GENCB macro 

execute form 175 

with parameter lists built by user 183, 185 
format 69 

generate a request parameter list at execution time 
summary 162 

generate an access methocf control block at 
execution time 
summary 161 


generate an exit list at execution time 
summary 162 
generate form 176 

reentrant example 179 
generating a request parameter list 80 
generating a request parameter list example 85 
generating an access method control block 69 
generating an access method control block 
example 75 
generating an exit list 76 
generating an exit list example 78 
inconsistent operand error 3 
linking to VSAM directly 187 
list form 175 
operand notation 181 
reason codes 10 
return codes 10 
generate form 

GENCB macro 176 
MODCB macro 176 
SIIOWCB macro 177 
TESTCB macro 178 
use of 178 

gcncratc-form keyword 173 
generating a request parameter list 
GENCB macro 80 
RPL macro 126 

generating an access method control block (GENCB 
macro) 69 
generating an exit list 
at assembly time 66 
GENCB macro 76 
G ET macro 
format 86 

retrieving a direct to sequential record example 94 
retrieving a keyed-direct record 92 
retrieving a keyed-sequential record (backward) 
example 

backward 87 
retrieving a record 
summary 162 

retrieving a relative record example 91 
retrieving a skip-sequential record, example 87 
retrieving an addressed-direct record example 93 
retrieving an addrcsscd-scqucntial record 
example 89 

retrieving keyed-sequential record example 
forward 86 
GETIX macro 
format 97 

retrieving an index record 
summary 163 
GSR option 

BLDVRP macro 48 

in MACRF parameter of the ACB macro 39 
GSR subparameter 
DLVRP macro 59 
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HALCRBA parameter 

in FIELDS parameter 136 
header entry 

in parameter lists of GENCB, MODCB, SHOWCB, 
and TESTCB macros 
coding example 185 
illustration 185 
using macros to build 185 


0 

ICI subparameter 

in MACRF parameter of the ACB macro 38 


IDAELEM macro 

185 

IDAGENC macro 

185 

IDAMODC macro 

185 

I DAS HOW macro 

185 

IDATEST macro 

185 

IN subparameter 



in MACRF parameter of the ACB macro 38 
index 

retrieval (GET1X macro) 97 
storing (PUTIX macro! 125 
INDEX option 

BLDVRP macro 48 

indirect address for S-type address constant 33 
indirect S-type address constant 69 
inserting records 
keyed-direct 118 
keyed-sequential 111, 115 
skip sequential 116 
IO parameter 

in TESTCB macro 153 
IOPID parameter 

in EXLST macro 66 


0 

JRNAD parameter 

in EXLST macro 67 
in GENCB macro 77 
in SHOWCB macro 140 
in TESTCB macro 150 


KEQ subparameter 

in OPTCD parameter of RPL macro 129 
KEY subparameter 

in MACRF parameter of the ACB macro 38 
in OPTCD parameter of RPL macro 128 
key-direct deletion 
example 63 
kcy-scquenccd data set 

used in ACQRANGE macro 44 
KEYLEN parameter 
BLDVRP macro 47 
in FIELDS parameter 136,143 
in GENCB macro 82 
in RPL macro 127 
keywords 

execute form 173 
generate form 173 
list form 172 
KGE subparameter 

in OPTCD parameter of RPL macro 130 
KSDS parameter 

in TESTCB macro 146 


L 


LDS parameter 

in TESTCB macro 146 
LENGTH parameter 

in GENCB macro 72, 77, 82 
in SHOWCB macro 133, 139, 141 
LERAD parameter 

in EXLST macro 67 
in GENCB macro 77 
in SHOWCB macro 140 
in TESTCB macro 150 
linear data set 

error in VERIFY macro 155 
logical error reason codes 23 
linking to VSAM directly 187 
list form 

BLDVRP macro 174 
GENCB macro 175 
MODCB macro 176 
SHOWCB macro 177 
TESTCB macro 177 
use of 178 
list-form keyword 172 
list, execute, generate formats 174 
list, execute, generate forms of macros 171 
list, parameter 

of GENCB, MODCB, SHOWCB, and TESTCB 
macros 183 
LOC parameter 

in GENCB macro 72, 77, 82 
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removal from the BLDVRP macro 47 
LOC subparameter 

in OPTCD parameter of RPL macro 130 
local shared resources 
ACB example 43 
locate mode 

with control interval access 
with shared resources 132 
lower case, in notation convention vii 
l.RD subparameter 

in OPI'CD parameter of RPL macro 129 
LRECL parameter 

in FIELDS parameter 136 
LRU subparametcr 

in WRTBFR macro 157 
LSR option 

BLDVRP macro 48 
DLVRP macro 59 

in MACRF parameter of the ACB macro 39 
LSR pool 

example in BLDVRP macro 50 


M 


MACRF parameter 
in ACB macro 37 
in GENCB macro 72 
in TESTCB macro 147 

macro instruction return codes and reason codes 1 
macros 

descriptions 1 
-summary of i59 
MARE A parameter 
in ACB macro 40 
in FIELDS parameter 135 
in GENCB macro 73 
MARK parameter 

in MRKBFR macro 106 
marking records inactive 124 
message area 

header information 8 
message list 9 
OPEN/CLOSE 7 
provided by VSAM 7 
MLEN parameter 
in ACB macro 40 
in FIELDS parameter 135 
in GENCB macro 73 
MNTACQ macro 
format 98 
summary 163 
MODCB macro 
example 101 
execute form 176 

reentrant example 180 
with parameter lists built by user 183 
format 100 
generate form 176 


linking to VSAM directly 187 
list form 176 

modify a request parameter list example 105 
modify an exit list exampte 103 
modifying a request parameter list 104 
summary 164 
modifying an ACB 100 
summary 163 
modifying an exit list 
format 102 
summary 163 
operand notation 181 
reason codes 10 
remote-list form 

reentrant example 179 
return codes 10 
MODE option 

BLDVRP macro 48 
MODE parameter 
DLVRP macro 59 
in CLOSE macro 55 
in OPEN macro 107 

modifying and displaying the RECLEN field of an RPL 
directly 188 

move mode of control interval access 
with shared resources 132 
MRKBFR macro 
format 106 
invalidating a buffer 
parameters for 106 
reason codes 106 
summary 164 
MSG A REA parameter 

in HELDSjsarameter 143 
in GENCB macro 82 
in RPL macro 127 
MSGLEN parameter 

in FIELDS parameter 143 
>*>in GENCB macro 82 
in RPL macro 127 
MVE subparameter 

in OPTCD parameter of RPL macro 130 


N 


NCI subparameter 

in MACRF parameter of the ACB macro 38 
NCIS parameter 

in FIELDS parameter 136 
NDELR parameter 

in FIELDS parameter 136 
NDF subparameter 

in MACRF parameter of the ACB macro 38 
NEXCP parameter 

in FIELDS parameter 136 
NEXT parameter 

in FIELDS parameter 136 
NFX subparameter 
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in MACRF parameter of the ACB macro 38 
NINSR parameter 

in FIELDS parameter 136 
NIS subparameter 

in MACRF parameter of the ACB macro 39 
NIXL parameter 

in FIELDS parameter 136 
NLOGR parameter 

in FIELDS parameter 136 
NO subparameter, in CATALOG parameter 
in ACB macro 36 
in GENCB macro 71 
in TESTCB macro 147 
restriction 36,71 
NRETR parameter 

in FIELDS parameter 136 
NRM option 

in MACRF parameter of the ACB macro 39 
NRS option 

in MACRF parameter of the ACB macro 39 
NSP subparameter 

in OPTCD parameter of RPL macro 129 
NSR option 

in MACRF parameter of the ACB macro 39 
NSSS parameter 

in FIELDS parameter 136 
NUB option 

in MACRF parameter of the ACB macro 39 
NUIW parameter 

in FIELDS parameter 137 
N U P suhparameter 

in OPFCD parameter of RPL macro 129 
NUPDR parameter 

in FIELDS parameter 137 
NWAITX subparameter 

in OPFCD parameter of RPL macro 130 
NXTRPL parameter 

in FIELDS parameter 143 
in GENCB macro 83 
in RPL macro 128 


o 


OBJECT parameter 

in SIIOWCB macro 134 
in TESTCB macro 146 
OF LAGS parameter 

in TESTCB macro 147 
OPEN macro 

connecting program and data 
summary 164 
format 107 

open two data sets example 108 
parameter list above 16M example 108 
reason codes 2 

use of SHOWCB macro 2 
use of VERIFY command 2 
return codes 1 


shared resources 
reason codes 3 

OPEN/CLOSE message area for multiple 
reason/warning messages 7 
opening a data set 
for processing 107 
OPENOBJ parameter 

in TESTCB macro 148 
operand notation 
GENCB 181 
MODCB 181 
SHOWCB 181 
TESTCB 181 
operands 

optional 174 
required 174 

operands with GENCB, MODCB, SIIOWCB, 
TESTCB 181 
OPTCD parameter 

in GENCB macro 83 
in RPL macro 128 
in TESTCB macro 153 
OPTCD subparameter 


ACQRANGEi 

macro 

GETIX macro 

97 

in RPL macro 

130 

MNTACQ macro 98 

PUT1X macro 

125 

SCI!BFR macro 132 

optional operands 

174 


or sign, in,notation convention vii 
OUT subparameter 

in MACRF parameter of the ACB macro 39 
in MRKBFR macro 106 


0 

parameter list 

of GENCB, MODCB, SHOWCB, and TESTCB 
macros 183 

passing control directly to VSAM 187 
PASSWD parameter 
in ACB macro 40 
in FIELDS parameter 135 
in GENCB macro 73 
physical error analysis 

with control interval access 26 
physical error message 

displayed in SHOWCB macro example 144 
format 30 
RBA field 26 
POINT macro 
format 109 
position example 109 
positioning for access 
summary 164 
positioning 

following logical errors 24 
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of reason codes 25 

positioning for access (POINT macro) 109 
PUT macro 

addressed-sequential update example 123 
format 111 

keyed-direct insertion example 118 
keyed-direct update example 121 
keyed-sequential insertion example 111, 115 
keyed-sequential update example 120 
loading a relative record data set 113 
marking records inactive example 124 
recording RBAs when loading example 112 
skip-sequential insertion example 116 
storing a record 
summary 164 
PUTIX macro 
format 125 
storing an index record 
summary 165 


R 


RBA field 

in physical error message 26 
RBA parameter 

in I'll-LOS parameter 143 
RBA values 

CNVTAD macro 58 
passed to MNTACQ macro 58 
reason codes 

from OPEN macro 2 
use of SUOWCB 2 
from request macros (GET, PUT, etc.) 

physical errors, control interval access 26 
in control block manipulation macros 10 
in GENCB macro 10 
in MODCB macro 10 
in SI IOWCB macro 10 
in TESTCB macro 10 
logical errors 17 
physical errors 26 
positioning state 25 

request parameter list feedback area 13, 15 
shared resources from OPEN macro 3 
successful request 15 

use of VERIFY command in OPEN macro 2 
RECLEN field (record length) of an RPL 
modifying and displaying 188 
RECLEN parameter 

in FIELDS parameter 143 
in GENCB macro 83 
in RPL macro 130 
record 

retrieval (GET macro) 86 
record length (RECLEN field) of an RPL 
modifying and displaying 188 
record management 

return codes and reason codes 13 


reentrant program 33 
register notation 33, 69 
relative record data set 

used in ACQRANGE macro 44 
relative record number 
used as a key 91 

releasing exclusive or shared control 
MRKBFR macro 106 
REPL parameter 

in TESTCB macro 147 
request macros 
CHECK 51 
ENDREQ 61 
ERASE 63 
GET 86 

physical reason codes from 26 
POINT 109 
PUT 111 

request parameter list 
chaining 81, 126 
chaining example 84 
chaining in G ET macro 96 
chaining not allowed 

with SCI IBI R macro 132 
with WRTBFR macro 156 
changing 104 

component codes from component code field 14 
displaying fields in SI IOWCB macro 141 
generating at assembly time 
generating at execution time 80 
generating with GENCB macro example 85 
modifying 104 

reason codes from feedback area 15 
testing in TESTCB macro 152 
testing in TESTCB macro example 154 
with the GENCB macro 81 
with the RPL macro 126 
required operands 174 
resource sharing ? \ 
retrieving a record 
for deletion 64 
retrieving an index record 13 
return codes 

checking, example 51 

from asynchronous request 14 

from BLDVRP macro 30 

from CLOSE macro 6 

from DLVRP macro 31 

from end-of-volume 31 

from macros used to share resources 30 

from OPEN macro 1 

from RPL 13 

in control block manipulation macros 10 
in GENCB macro 10 
in MODCB macro 10 
in SHOWCB macro 10 
in TESTCB macro 10 
synchronous request 14 
return codes and reason codes from OPEN 1 
reusable data set 

specifying in ACB macro processing). 39 
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RKP parameter 

in FIELDS parameter 137 
RLS subparameter 

in MRKBFR macro 106 
RMODE3I parameter 

example in BLDVRP macro 49 
example in the GENCB macro 75 
in ACB macro 40, 43 
in BLDVRP macro 47 
in OPEN macro 107 
in the GENCB macro 73 
in the MODCB macro 100 
RPL component code 13 
RPL condition code 13, 15 
RPL feedback area 13 
RPL feedback word 13 
RPL macro 
example 131 
format 126 

generate a request parameter list at assembly time 
summary 165 
RPL operand 

RECLEN field (record length) 
modifying and displaying 188 
RPL parameter 

in ACQFLANGE macro 44 
in BLK parameter in GENCB macro 81 
in CHECK macro 51 
in CNVTAD macro 57 
in ENDREQ macro 61 
in. ERASE macro 61 
in GET macro 86 
in GETIX macro 97 
in MNTACQ macro 98 
in MODCB macro 104 
in MRKBFR macro 106 
in POINT macro 109 
in PUT macro 111 
in PUTIX macro 125 
in SCIIBFR macro 132 
in SHOVVCB macro 141 
in TESTCB macro 152 
in VERIFY macro 155 
in WRTBFR macro 156 
MNTACQ macro 98 
RPL reason code 13 
RPL return code 13 
RPLLEN parameter 

in FIELDS parameter 143 
RRDS parameter 

in TESTCB macro 147 
RST subparameter 

in MACRF parameter of the ACB macro 39 


a 

S-type address constant 33, 69 
SCHBFR macro 
summary 165 

SCRA subparameter, in CRA parameter 
in ACB macro 36 
in GENCB macro 72 
in TESTCB macro 147 
restriction 36,72 
search argument 
full key 131 
generic (partial) key 129 
SEQ subparameter 

in MACRF parameter of the ACB macro 38 
in OPTCD parameter of RPL macro 128 
sequential insert strategy 
specified in ACB 38 
sequential processing 

reason code positioning state 25 
shared resource macros 
return codes 30 
shared resources 34 
S HA REOPTIONS 4 

incompatible with deferring write requests 3 
sharing 

control blocks 

based on DDNAME 34 
based on DSNAME 34 
parameter lists 173 

among BLDVRP, DLVRP, GENCB, MODCB, 
SHOVVCB, and TESTCB 171 
reentrant form 178 
SHOVVCB macro 

as used with CLOSE macro return codes 6 
display an ACB example 137 
displaying a physical error message example 144 
displaying an access method control block 
example 137 

displaying an exit list address example 138 
displaying fields of a request parameter list 141 
summary 166 

displaying fields of an access method control 
summary 166 

displaying fields of an access method control 
block 133 

displaying fields of an exit list 139 
summary 166 

displaying the length of an exit example 140 
execute form 177 

with parameter lists built by user 183 
format 133 
generate form 177 
linking to VS AM directly 187 
list form 177 
operand notation 181 
reason codes 10 

reason codes from OPEN macro 2 
return codes 10 
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SHRPOOL parameter 
ACB macro 41 
BLDVRP macro 47 
DLVRP macro 59 
in GENCB macro 74 
SIS option 

in MACRF parameter of the ACB macro 39 
skip-sequential processing 

reason code positioning state 25 
SKP subparameter 

in MACRF parameter of the ACB macro 38 
in OPTCD parameter of RPL macro 128 
SPAN parameter 

in TESTCB macro 147 
SSWD parameter 

in TESTCB macro 147 
STM ST parameter 

in FIELDS parameter 137 
storage requirements, I/O buffers 36, 70 
storing a record (PUT macro) 111 
storing an index record 13 
string extension, dynamic 35, 38 
STRMAX parameter 

in FIELDS parameter 135 
STRNO parameter 

BLDVRP macro 48 
in ACB macro 41 
in FIELDS parameter 135 
in GENCB macro 74 
summary of macros 159 
suspending processing 
overlap processing 52 
request for many records 53 
SYN subparameter 

in OITCD parameter of RPL macro 129, 130 
SYNAD exit routine 

physical error message 26 
SYNAD parameter 

in EXLST macro 67 
in GENCB macro 77 
in SIIOWCB macro 140 
in TESTCB macro 150 
synchronizing end of data 
(VERIFY macro) 155 
synchronous processing 

specified in MODCB macro 104 
specified in RPL macro 130 
synchronous request 
return codes 14 


0 

T On TYPE parameter in CLOSE macro) 7 
temporary CLOSE macro 7 
terminating a request 
ENDREQ macro 61 

terminating a request before completion 62 
TESTCB macro 154 


execute form 178 

with parameter lists built by user 183 
format 145, 150 
generate form 178 
linking to VSAM directly 187 
list form 177 
operand notation 181 
reason codes 10 
return codes 10 

testing a field of a request parameter list 
summary 168 

testing a field of an access method control block 
summary 167 

testing a field of an exit list 150 
summary 168 

testing a request parameter list 152 
testing fields of an access method control 
block 145 

testing for data set attributes 148 
using a branch table 151 
testing a control block 
exit list 150 

request parameter list 152 
transaction ID 

writing related requests 157 
TRANSID parameter 

in FIELDS parameter 143 
in GENCB macro 83 
in RPL macro 130 
TRANSID subparameter 
SCIIBFR macro 132 
TRN subparameter 

in WRTBFR macro 157 
TYPE parameter 

BLDVRP macro 48 
DLVRP macro 59 
in CLOSE macro 7, 55 
in WRTBFR macro 156 



UBF option 

in MACRF parameter of the ACB macro 39 
UCRA subparameter, in CRA parameter 
in ACB macro 36 
in GENCB macro 72 
in TESTCB macro 147 
restrictions 36,72 
UIW parameter 

in FIELDS parameter 137 
underlining, in notation convention vii 
UNQ attribute, in ATRB parameter 147 
UPAD parameter 

in EXLST macro 67 
UPD subparameter 

in OPTCD parameter of RPL macro 129 
updating records 


Index 



See also storing a record, lengthening a record, and 
shortening a record 
addressed-sequential 123 
example 120 
keyed-direct 121 
keyed-sequential 120 
upgrade set 

status following request that fails 14 
upper case, in notation convention vii 
use of list, execute, generate forms 178 
user buffering 39 


□ 

VERIFY command 
use in OPEN macro 
reason codes 2 
VERIFY macro 
. -f format 155 
summary 168 

VS AM macro formats and examples 


w 


WAITX subparameter 

iff OPTO> parameteref RPL macro* 130 
WAREA parameter 
in GENCB 

generating request parameter list 83 
in GENCB macro 

generating access method control block 74 
generating exit list 74, 77 
WCK parameter 


in TESTCB macro 147 
work area 

processing a record in 83, 126 
relation to I/O buffer 83, 126 
specifying 

generating access method control block 74 
generating exit list 77 
generating request parameter list 83 
work data set 

specifying in ACB macro 39 
WRTBFR macro 
format 156 
summary 169 


X 


XINVALID subparameter 
in MRKBFR macro 106 



YES subparameter, in CATALOG parameter 
in ACB macro 36 
in GENCB macro 71 
in TESTCB macro 147 
restriction 36, 71 


Numerics 


31 -bit format 

ACB example 43 


33 
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